Upnote MCP Server

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

Features

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

Installation

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

# Install dependencies using Bun
bun install

Configuration

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

Claude Desktop Configuration

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.

Available Tools

upnote_create_note

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

upnote_open_note

Open an existing note by its ID.

Parameters:

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

upnote_create_notebook

Create a new notebook in Upnote.

Parameters:

• title (required): Name for the new notebook

upnote_open_notebook

View all notes in a specific notebook.

Parameters:

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

upnote_view_tag

View all notes with a specific tag.

Parameters:

• tag (required): Tag name to filter notes

upnote_open_filter

View notes using a custom filter.

Parameters:

• filterId (required): Custom filter identifier

upnote_view

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)

upnote_search

Search for notes in Upnote.

Parameters:

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

Usage Examples

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'"

How It Works

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

Requirements

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

Development

To run the server directly:

bun run index.ts

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

Platform Support

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.

Finding Upnote IDs

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.

Troubleshooting

Server not connecting

• 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

Upnote not responding

• 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

Contributing

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

License

MIT

Credits

Built using the Model Context Protocol SDK by Anthropic.

Upnote is a trademark of Upnote.