SkillAgentSearch skills...

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-mcp

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

71/100

Supported Platforms

Claude Code
Claude Desktop
OpenAI Codex

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.

Substance
30/30
Structure
20/20
Description
12/15
Adoption
3/20
Freshness
15/15

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.

SkillScoreStarsUpdatedFormat
upnote-mcp (this skill)by andreiGl7135d agoMCP Server
taste-skillby Leonxlnx100117.8k9d agoCLAUDE.md
Agent-Reachby Panniantong100112.8k10d agoCLAUDE.md
rufloby ruvnet10082.0ktodayCLAUDE.md
headroomby headroomlabs-ai10079.9ktodayCLAUDE.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.

UpNote 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_note can 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. Set UPNOTE_DB to point it elsewhere.
  • python.org's Python 3.12 or newer, and clang from 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:

  1. Give the launcher Full Disk Access: System Settings, Privacy & Security, Full Disk Access, press +, then Cmd+Shift+G and paste ~/.claude/mcp-servers/upnote-mcp-launcher.
  2. Register the launcher with your client.
  3. 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

View on GitHub
GitHub Stars3
CategoryDevelopment
Updated5d ago
Forks0

Languages

Python

Trust signals

87/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

2 low