upnote-mcp

upnote-mcp is a read-only MCP server for reading local UpNote data from SQLite over stdio.

This is an unofficial project and is not affiliated with, endorsed by, or maintained by UpNote.

Features

• search_notes: search notes by title, body text, or summary
• list_recent_notes: list the most recently updated notes
• list_notes_this_week: list notes updated during the current week
• list_notes_this_month: list notes updated during the current month
• find_notes: combine period, keyword, and tag filters in one call
• find_and_open_note: find matching notes and open the most recent match in UpNote
• open_note: open a note in the UpNote app by note ID
• get_note: fetch the full contents of a note by note ID
• open_notebook: open a notebook in the UpNote app by notebook ID
• list_notebooks: list notebooks with note counts
• create_note: create a new note through UpNote's official URL scheme
• list_tags: list tags
• search_by_tag: list notes for a tag

This project is intentionally read-only. It does not write to the UpNote database. Safe note creation and open actions are performed through UpNote's official URL scheme instead of direct database writes.

Package Name

This package is prepared to be published as @bellx2/upnote-mcp.

Requirements

• macOS
• bun installed on the machine that runs the server
• UpNote desktop app installed
• Default UpNote database path:

~/Library/Containers/com.getupnote.desktop/Data/Library/Application Support/UpNote/upnote.sqlite3

If your database lives somewhere else, set UPNOTE_DB.

Install

bun install

Run

bun run start

For normal use, prefer the published package:

bunx @bellx2/upnote-mcp

or:

npx @bellx2/upnote-mcp

npx support still depends on bun being installed, because this package uses Bun-specific APIs such as bun:sqlite.

For development with file watching:

bun run dev

Environment Variables

• UPNOTE_DB: absolute path to upnote.sqlite3

Example:

export UPNOTE_DB="$HOME/Library/Containers/com.getupnote.desktop/Data/Library/Application Support/UpNote/upnote.sqlite3"

Permissions

On first run, your MCP client may show permission prompts for command execution and local file access.

This is expected because the server:

• launches through bun
• reads your local UpNote SQLite database
• may open the UpNote app for open_note, open_notebook, or create_note

If you deny these permissions, note search and retrieval will not work. After granting access, you may need to restart the MCP server in Cursor or Claude Desktop.

MCP Config Example

Recommended: published package

Cursor

{
  "mcpServers": {
    "upnote": {
      "command": "bunx",
      "args": ["@bellx2/upnote-mcp"]
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "upnote": {
      "command": "bunx",
      "args": ["@bellx2/upnote-mcp"]
    }
  }
}

Local development checkout

Cursor

{
  "mcpServers": {
    "upnote": {
      "command": "/absolute/path/to/bun",
      "args": ["run", "/absolute/path/to/upnote-mcp/src/index.ts"]
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "upnote": {
      "command": "/absolute/path/to/bun",
      "args": ["run", "/absolute/path/to/upnote-mcp/src/index.ts"]
    }
  }
}

Example Workflows

Try prompts like:

• Search UpNote for "travel" and show me the first result
• Show me my 10 most recent UpNote notes
• Show me this week's notes
• Show me this month's notes
• Find this week's AI notes
• Open this week's AI note
• Find this month's notes tagged meeting
• Open the latest note tagged meeting
• List my UpNote tags and open the note that matches the tag "meeting"
• Find notes about "launch", summarize them, and create a new UpNote note with the summary
• List notebooks and open the one named "Research"

Tool Reference

search_notes

Input:

{
  "query": "travel",
  "limit": 5
}

list_recent_notes

Input:

{
  "limit": 10
}

list_notes_this_week

Input:

{
  "limit": 20
}

list_notes_this_month

Input:

{
  "limit": 20
}

find_notes

Input:

{
  "period": "this_week",
  "query": "AI",
  "limit": 10
}

Or:

{
  "period": "this_month",
  "tag": "meeting",
  "limit": 10
}

find_and_open_note

Input:

{
  "period": "this_week",
  "query": "AI",
  "limit": 10
}

Or:

{
  "period": "recent",
  "tag": "meeting",
  "limit": 10
}

get_note

Input:

{
  "id": "019fd239-a98a-742b-b75b-cee66e7aa830"
}

open_note

Input:

{
  "id": "019fd239-a98a-742b-b75b-cee66e7aa830"
}

open_notebook

Input:

{
  "id": "3f03c742-1270-4d35-a5bc-c7d98580d6fc"
}

list_notebooks

Input:

{}

list_tags

Input:

{}

search_by_tag

Input:

{
  "tag": "meeting",
  "limit": 5
}

create_note

Input:

{
  "title": "Meeting Notes",
  "text": "# Summary\n\nDraft created by MCP.",
  "markdown": true,
  "newWindow": false
}

Verification

bun run check
bun run smoke

Japanese README

The previous Japanese README is available at README_ja.md.