A Model Context Protocol (MCP) server that enables AI assistants to interact with Upnote using its x-callback-url API.

This MCP server provides comprehensive integration with Upnote, allowing you to:

• Create Notes: Create new notes with custom titles, content, and markdown formatting
• Open Notes: Open specific notes by their ID
• Manage Notebooks: Create new notebooks and view notebook contents
• Tag Management: View all notes with specific tags
• Custom Filters: Access notes using custom filter IDs
• Dynamic Views: Navigate to different Upnote sections (all notes, quick access, templates, trash, etc.)
• Search: Search for notes across your Upnote library

# Clone or navigate to the project directory
cd upnote-mcp

# Install dependencies using Bun
bun install

To use this MCP server with Claude Desktop or other MCP clients, add it to your MCP configuration file:

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration:

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

Replace /absolute/path/to/upnote-mcp/ with the actual path to your installation.

Create a new note in Upnote.

Parameters:

• title (optional): Title for the new note
• text (optional): Content of the note
• notebook (optional): Target notebook identifier
• markdown (optional, default: true): Enable Markdown formatting
• new_window (optional, default: false): Open note in new window

Open an existing note by its ID.

Parameters:

• noteId (required): The unique identifier of the note
• new_window (optional): Open note in new window

Create a new notebook in Upnote.

Parameters:

• title (required): Name for the new notebook

View all notes in a specific notebook.

Parameters:

• notebookId (required): Identifier of the notebook to display

View all notes with a specific tag.

Parameters:

• tag (required): Tag name to filter notes

View notes using a custom filter.

Parameters:

• filterId (required): Custom filter identifier

Dynamic view command for various Upnote sections.

Parameters:

• mode (optional): View type - all_notes, quick_access, templates, trash, notebooks, tags, filters, all_notebooks, all_tags
• noteId (optional): Opens specific note in editor
• notebookId (optional): Required when mode is 'notebooks'
• tagId (optional): Required when mode is 'tags'
• filterId (optional): Required when mode is 'filters'
• spaceId (optional): Space identifier (defaults to current space)

Search for notes in Upnote.

Parameters:

• query (required): Search query string
• spaceId (optional): Space identifier to search within

Once configured with Claude Desktop, you can interact with Upnote using natural language:

• "Create a new note titled 'Meeting Notes' with the text 'Discussed Q4 goals'"
• "Open my notebook with ID abc123"
• "Search for notes containing 'project ideas'"
• "Create a new notebook called 'Research'"
• "Show me all notes tagged with 'important'"

This MCP server uses Upnote's x-callback-url scheme to interact with the application. When a tool is invoked:

1. The server constructs a properly formatted upnote:// URL with the appropriate parameters
2. The URL is executed using the system's open command (macOS)
3. Upnote receives the URL and performs the requested action
4. The server returns a success message to the MCP client

• Upnote: Must be installed on your system
• Bun: v1.3.5 or later
• macOS: Currently uses the open command (macOS-specific)

To run the server directly:

bun run index.ts

The server communicates via standard input/output (stdio) using the MCP protocol.

Currently optimized for macOS using the open command to trigger URL schemes. Support for other platforms may require modifications to the URL execution mechanism in the executeUpnoteUrl function.

To use tools that require IDs (noteId, notebookId, filterId):

1. Note IDs: Can be found in Upnote's note sharing or export features
2. Notebook IDs: Check Upnote's settings or use the app's developer tools
3. Filter IDs: Available in custom filter settings

Refer to Upnote's documentation for more details on obtaining these identifiers.

• Ensure the path in claude_desktop_config.json is absolute and correct
• Verify Bun is installed and accessible in your PATH
• Restart Claude Desktop after configuration changes

• Confirm Upnote is installed and running
• Check that the x-callback-url endpoints are enabled in Upnote
• Verify the IDs you're using are correct and accessible

This is a community project. Contributions, bug reports, and feature requests are welcome!

MIT

Built using the Model Context Protocol SDK by Anthropic.

Upnote is a trademark of Upnote.