upnote-mcp
MCP server that lets Claude and Codex search, read and edit your UpNote notes (macOS)
Install / Use
claude mcp add andreiGl -- npx -y github:andreiGl/upnote-mcpIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of upnote-mcp
upnote-mcp scores 71/100 on our quality scale, 3863rd of 4,720 Development & Engineering skills we index.
Its MCP Server is 21 KB long, well organised into 19 sections with 11 code examples: a thorough specification that gives an agent plenty to work with.
It has 3 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 5 days ago, so upnote-mcp is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 87/100, with 2 cautions from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
upnote-mcp compared with similar skills
All 4 of these similar skills score higher than upnote-mcp; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| upnote-mcp (this skill)by andreiGl | 71 | 3 | 5d ago | MCP Server |
| taste-skillby Leonxlnx | 100 | 117.8k | 9d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.8k | 10d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 82.0k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.9k | today | CLAUDE.md |
Frequently asked questions
- How do I install upnote-mcp?
- Run
claude mcp add andreiGl -- npx -y github:andreiGl/upnote-mcp. The install tabs above show the steps for each supported agent. - Which AI agents does upnote-mcp work with?
- It is written for Claude Code, Claude Desktop and OpenAI Codex, as a MCP Server file. Other agents that read the same format can often use it too.
- Is upnote-mcp safe to use?
- It is MIT-licensed and scores 87/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is upnote-mcp still maintained?
- The repository was last updated 5 days ago, so upnote-mcp is actively maintained.
Skill content
View source on GitHubUpNote MCP server
Let Claude and Codex work with your UpNote notes on macOS.
UpNote has no public API, so this MCP server reads the app's local database (read-only)
and makes every change through UpNote's own upnote:// links.
Ask in plain language:
- "Find my notes about JSON Patch and summarize them."
- "What did I change this week?"
- "Create a note in Get Started with a checklist for tomorrow."
- "Add a follow-up item to my Plans note."
- "In my Plans note, change Triage to In progress." Claude previews the edit first.
It works with Claude Code, Claude Desktop and Codex. It has sixteen tools: search, read, create, edit, append, insert under a heading, move to another notebook, make a collapsible section, change tags, move to Trash and back, and open a note in the app.
Unofficial. UpNote has no editing API, so this server depends on the app's local data format and two undocumented links (trash and restore). It was built against UpNote 9.22.2 to 9.22.6 (data version 17) and the author runs it on 9.22.9. An UpNote update can break it. The server checks the database format on every connection and fails with a clear message instead of returning wrong results. macOS is the tested platform; Windows support is new and untested on a real machine (see Requirements).
Safety and known risks
- Reads cannot change anything. The database is opened read-only, and an authorizer refuses everything except reading.
- Writes go through UpNote. The server never writes to the database. UpNote makes each change and syncs it as if you had made it by hand. Text sent to UpNote is cleaned of anything that could run code or send data out.
- An edit makes a new note. UpNote cannot change a note in place. An edit creates a
checked new version and then moves the original to Trash, where
restore_notecan bring it back. The new note gets a new id and creation date. Version History stays with the original, and pin and bookmark must be set again by hand. Every edit shows a preview with warnings first. The tools refuse notes that have attachments or images, links from other notes, a web share link, or a template. - Nothing is deleted for good. No tool empties Trash.
- UpNote once emptied a notebook's membership list. On 2026-10-11 a note created in a notebook of 351 left it holding 1 (UpNote 9.22.6, once, during its daily backup and re-sync). The notes stayed intact. The server cannot prevent this, but it checks the notebook before and after each change and reports a loss. UpNote's daily backup is the way back. See Limits and known issues.
- Full Disk Access. macOS needs it to read UpNote's data. You grant it to a small launcher that runs only this server. See Full Disk Access for what that allows.
Requirements
- macOS, with UpNote installed from the Mac App Store. The server reads
~/Library/Containers/com.getupnote.desktop/Data/Library/Application Support/UpNote/upnote.sqlite3. SetUPNOTE_DBto point it elsewhere. - python.org's Python 3.12 or newer, and
clangfrom the Xcode Command Line Tools (xcode-select --install) to build the launcher. Full Disk Access explains why the server runs this way. - UpNote running, for any tool that changes a note or opens the app.
Windows
Windows support is new and untested on a real Windows machine - treat it as a preview. The
server reads %APPDATA%\UpNote\upnote.sqlite3 (UpNote's Windows data folder; set UPNOTE_DB
if your install keeps it elsewhere). Operation state goes to
%LOCALAPPDATA%\upnote-mcp. No Full Disk Access and no launcher are needed: the database
sits in your own profile, so plain Python can read it. Installation steps are under
Install. Links to UpNote go through the OS URL handler, so UpNote must be
running, and they open the app visibly (Windows has no background-start equivalent of macOS
open -g).
Install
git clone https://github.com/andreiGl/upnote-mcp ~/.claude/mcp-servers/upnote-mcp
~/.claude/mcp-servers/upnote-mcp/install.sh
The script links the folder into ~/.claude/mcp-servers/, builds a virtual environment, and
builds and signs the launcher. It changes no client setting. When it finishes, it prints the
next steps, which are:
- Give the launcher Full Disk Access: System Settings, Privacy & Security, Full Disk
Access, press
+, thenCmd+Shift+Gand paste~/.claude/mcp-servers/upnote-mcp-launcher. - Register the launcher with your client.
- Restart the client and ask Claude to run
check_upnote_setup.
Windows install
git clone https://github.com/andreiGl/upnote-mcp
cd upnote-mcp
python -m venv venv
venv\Scripts\pip install "mcp==2.2.0"
No launcher and no special permissions: the database sits in your own profile, so a plain Python process can read it. Register the server with your client as a stdio command. Claude Code:
claude mcp add --scope user upnote -- venv\Scripts\python -I server.py
For other clients, the command is the same shape: venv\Scripts\python -I server.py from the
checkout folder. If the tools report a missing database, find upnote.sqlite3 in your UpNote
install and set UPNOTE_DB to its full path - either in the client's env block for the
server or system-wide. See Windows for the caveats: this port is new and has not
run on a real Windows machine yet.
Register with a client
Claude Code, for all projects:
claude mcp add --scope user upnote -- ~/.claude/mcp-servers/upnote-mcp-launcher
Claude Desktop: add the launcher by its absolute path to
~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"upnote": {
"command": "/Users/you/.claude/mcp-servers/upnote-mcp-launcher"
}
}
}
Codex:
codex mcp add upnote -- /Users/you/.claude/mcp-servers/upnote-mcp-launcher
Or add this entry to ~/.codex/config.toml. Merge it with an existing upnote entry rather
than adding a duplicate:
[mcp_servers.upnote]
command = "/Users/you/.claude/mcp-servers/upnote-mcp-launcher"
startup_timeout_sec = 20
tool_timeout_sec = 30
enabled_tools = ["search_notes", "list_notes", "get_note", "list_notebooks", "list_tags", "run_select", "check_upnote_setup", "create_note", "replace_note", "append_to_note", "insert_after_heading", "move_note", "make_section", "move_note_to_trash", "restore_note", "open_in_upnote"]
These are the server's sixteen tools. Keep the client's normal approval policy; no blanket automatic approval is needed.
Other clients
The server is a standard MCP stdio process, so any client that can launch a local process on this Mac can use it. Only the three clients above are tested. The clients below support local stdio servers and are expected to work; the registration shape is the same everywhere - point the client at the launcher. Use Copilot Chat in Agent mode with these; tool calls from chat mode don't run tools.
Copilot, VS Code - .vscode/mcp.json:
{
"servers": {
"upnote": {
"type": "stdio",
"command": "/Users/you/.claude/mcp-servers/upnote-mcp-launcher"
}
}
}
JetBrains IDEs: same JSON in the MCP configuration from Copilot Chat → Agent → Configure MCP server. Copilot Business or Enterprise may need the "MCP servers in Copilot" policy enabled.
Gemini CLI - ~/.gemini/settings.json:
{
"mcpServers": {
"upnote": {
"command": "/Users/you/.claude/mcp-servers/upnote-mcp-launcher",
"timeout": 30000
}
}
}
Keep trust at its default (false) so tool calls stay confirmed.
Grok CLI - ~/.grok/config.toml:
[mcp_servers.upnote]
command = "/Users/you/.claude/mcp-servers/upnote-mcp-launcher"
enabled = true
Perplexity Mac app: install the PerplexityXPC helper, then add a custom connector whose command is the launcher path, and enable it in Perplexity's settings.
Muse Code: add the launcher under mcp_servers in its MCP configuration, same shape as
Gemini's. The consumer Muse app has no self-serve path - connectors go through Meta's reviewed
directory.
Web and mobile clients can't use this server: it reads the database file and opens links on the machine where UpNote runs, and they can launch neither.
Manual install
The script runs these steps:
/Library/Frameworks/Python.framework/Versions/3.12/bin/python3.12 -m venv ~/.claude/mcp-servers/upnote-mcp-venv
~/.claude/mcp-servers/upnote-mcp-venv/bin/python -m pip install 'mcp==2.2.0'
clang -O2 -o ~/.claude/mcp-servers/upnote-mcp-launcher ~/.claude/mcp-servers/upnote-mcp/launcher.c
codesign -s - -i ca.glotov.upnote-mcp-launcher -f ~/.claude/mcp-servers/upnote-mcp-launcher
Keep the mcp version in the venv in step with the one server.py declares. The launcher
always runs ~/.claude/mcp-servers/upnote-mcp/server.py, so the checkout must sit at that
path or be linked there.
macOS access and reconnecting
The launcher may need the Full Disk Access grant. The host app's permissions also matter: during local Codex desktop validation, its ChatGPT app needed Files & Folders, UpNote enabled even though the launcher already had access. Read the actual setup error and grant only the access needed.
Run check_upnote_setup before reading or changing notes. Reconnect MCP servers or start fresh
client sessions after a source or configuration change. A running session can keep its old server
process and tool catalog.
Upgrading
The running server keeps the server.py it started with, so restart your clients after an update.
For a plain checkout, run git pull in ~/.claude/mcp-servers/upnote-mcp. A Python-only update
does not need a rebuilt or re-signed launcher. Rebuilding the launcher loses its Full Disk Access
grant: remove it, add it back, and restart Claude.
To switch between versions without a gap, keep each version in its own folder, pause calls in every
client, replace the ~/.claude/mcp-servers/upnote-mcp link with a temporary sibling link and an
atomic rename, then reconnect the MCP servers. To roll back, restore only that link. Do not restore
a database or unrelated settings.
Tools
| Tool | What it does |
| :--- | :--- |
| search_notes | Finds notes containing all the given words in the title or body, case-insensitive in any language, optionally within a notebook, tag or date range |
| list_notes | Lists notes by last update or creation date, newest first, optionally within a notebook, tag or date range |
| get_note | Returns one note's text or HTML, in parts for long notes, with its attachments' names |
| list_notebooks | Lists notebooks with their paths and note counts |
| list_tags | Lists tags with note counts |
| run_select | Runs one read-only SQL query, for questions the other tools don't cover. It stops a query after ten seconds, refuses a value or a result over 20 MB or more than 64 columns, and reads attachment download links as NULL |
| create_note | Creates a note, optionally in a notebook and with tags, and returns its id once UpNote has saved it |
| move_note_to_trash | Moves a note to Trash |
| restore_note | Moves a note out of Trash |
| replace_note | Edits a note by creating a new version and trashing the original, after a preview; can also move it, remove tags or add them |
| append_to_note | Adds content to the end of a note, copying what's already there, the same way as replace_note |
| insert_after_heading | Adds content just under or just above a heading, copying the rest of the note unchanged, the same way as replace_note |
| move_note | Moves a note to another notebook by rebuilding it there unchanged, the same way as replace_note |
| make_section | Turns a heading and what's under it, up t
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
117.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.8kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
82.0k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.9kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
