Content
# upnote-lens-mcp
<!-- mcp-name: io.github.AwesomeHye/upnote-lens-mcp -->
A hybrid MCP server that lets your AI assistant work with your UpNote notes:
- **🔍 Find & search** notes by keyword across titles and bodies.
- **📖 Read & summarize** — it returns the *actual note text*, so the AI can
summarize, analyze, or answer questions about what you've written.
- **✍️ Create** new notes from the chat.
Under the hood: reads come from the local UpNote SQLite database (**read-only**),
so real content comes back as text; writes go through the `upnote://` URL scheme
(x-callback-url) and **never touch the database**.
> The write side (URL scheme) is based on [chadthornton/upnote-mcp](https://github.com/chadthornton/upnote-mcp) (MIT).
## Usage
Once it's registered, just talk to your AI assistant in plain language — it
picks the right tool for you. No commands or syntax to memorize. For example:
- "Summarize my UpNote notes about the Q3 roadmap."
- "Find notes where I mentioned Postgres tuning and pull out the key points."
- "What did I write about onboarding last month?"
- "Show me my 5 most recent notes."
- "Create a note titled 'Standup 6/4' with today's three priorities."
Reading, searching, summarizing, and creating all happen through natural
conversation.
## Requirements
- **macOS** — fully supported and verified.
- **Windows** — best-effort. URLs launch through the registered scheme handler,
and the default DB path is guessed under `%APPDATA%\UpNote\`. This path is
**not verified** by the author — if reads fail, set `UPNOTE_LENS_DB` (see below).
- Python 3.10+ (or just [uv](https://docs.astral.sh/uv/), which brings its own).
- UpNote desktop app installed.
## Install & register
### 🤖 Let AI install it (easiest)
Give your MCP client (Claude, etc.) a link to
[`llms-install.md`](llms-install.md) and it will run the steps and set everything
up for you.
### 🧑 Install it yourself
Pick the first option that fits what you already have. Each option includes how
to register it in Claude.
> **Claude Desktop config file** (referenced in each option):
> - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
> - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
#### Option 1 — with uv (recommended)
Requires [uv](https://docs.astral.sh/uv/) installed once
(`brew install uv`, or `curl -LsSf https://astral.sh/uv/install.sh | sh`).
After that there's **no package install step** — `uvx` downloads, caches, and
runs upnote-lens-mcp on demand.
Claude Code:
```bash
claude mcp add upnote-lens -- uvx upnote-lens-mcp
```
Claude Desktop:
```json
{ "mcpServers": { "upnote-lens": { "command": "uvx", "args": ["upnote-lens-mcp"] } } }
```
#### Option 2 — with pip (if you don't have uv)
```bash
pip install upnote-lens-mcp
```
Claude Code:
```bash
claude mcp add upnote-lens -- upnote-lens-mcp
```
Claude Desktop:
```json
{ "mcpServers": { "upnote-lens": { "command": "upnote-lens-mcp" } } }
```
#### Option 3 — from GitHub over HTTPS (if you don't have pip)
When you can't use PyPI/pip, install straight from the repo with uv. (No uv yet?
`curl -LsSf https://astral.sh/uv/install.sh | sh`.)
Claude Code:
```bash
claude mcp add upnote-lens -- uvx --from git+https://github.com/AwesomeHye/upnote-lens-mcp upnote-lens-mcp
```
Claude Desktop:
```json
{ "mcpServers": { "upnote-lens": { "command": "uvx", "args": ["--from", "git+https://github.com/AwesomeHye/upnote-lens-mcp", "upnote-lens-mcp"] } } }
```
## Tools
### Read (queries the local DB → returns real text)
| Tool | Description |
|---|---|
| `search_notes(query, limit=20)` | Substring search over title/body. Returns id, title, updated time, snippet |
| `get_note(note_id, include_html=False)` | Full title + body text of a note (optionally raw HTML) |
| `list_recent(limit=20)` | Most recently updated notes |
| `list_notebooks()` | Notebooks with note counts and parent |
| `list_notes_in_notebook(notebook_id, limit=50)` | Notes inside a notebook |
| `list_tags()` | Tags with note counts |
| `list_notes_by_tag(tag_title, limit=50)` | Notes carrying a tag |
### Write (`upnote://` URL scheme)
| Tool | Description |
|---|---|
| `create_note(title, content, notebook?, markdown=True, new_window=False)` | Create a note. `content` is Markdown by default. `notebook` matches by name. **Tags can't be set** (see below) |
| `open_note(note_id, new_window=False)` | Open an existing note in the app |
| `open_notebook(notebook_id)` | Open a notebook in the app |
> **Tag limitation**: UpNote's `note/new` URL scheme has no tag parameter, and
> hashtags placed in the body stay as plain text rather than becoming real tags
> (they only convert to tags when typed in the editor). If you need tags, add
> them manually in the app after the note is created.
## Override the DB path
If the database isn't in the default location (or you're on Windows), point at it
with an environment variable:
```
UPNOTE_LENS_DB=/path/to/upnote.sqlite3
```
Default paths:
- macOS: `~/Library/Containers/com.getupnote.desktop/Data/Library/Application Support/UpNote/upnote.sqlite3`
- Windows (best guess): `%APPDATA%\UpNote\upnote.sqlite3`
## License
MIT. See [LICENSE](LICENSE) for details.
The URL-scheme formats and launch approach on the write side are adapted from
chadthornton/upnote-mcp (MIT).
