# Upnote MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with [Upnote](https://getupnote.com) 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

```bash
# 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:**

```json
{
  "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:

```bash
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](https://help.getupnote.com/resources/x-callback-url-endpoints) 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](https://github.com/modelcontextprotocol) by Anthropic.

Upnote is a trademark of [Upnote](https://getupnote.com).