Memos MCP Server

A Model Context Protocol (MCP) server for Memos, enabling AI assistants to interact with your Memos instances.

Features

• 🔗 Multi-Instance Support: Connect to multiple Memos instances and query them individually or collectively
• 📝 Note Management: Create, read, update, and delete memos with full Markdown support
• 🏷️ Tag Management: List and manage tags across your memos
• 📎 Attachment Support: Upload and manage file attachments
• 🔖 Shortcuts: Create and manage saved filters
• 🔒 Secure Storage: API keys are stored locally in your configuration directory
• 🎚️ Tiered Tool Exposure: Control which tools are enabled to minimize context usage

Usage

With Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "memos": {
      "command": "npx",
      "args": ["-y", "@0xlimao/memos-mcp-server"]
    }
  }
}

Tool Tiers

The server supports three tiers of tools to minimize context usage:

| Tier | Flag | Description | |------|------|-------------| | Tier 1 | (default) | Core note-taking tools | | Tier 2 | --user-tools | User advanced features (PAT, webhooks) | | Tier 3 | --admin-tools | Instance administration | | All | --full-tools | All tools enabled |

Example configurations:

// Default: Only note-taking tools
{
  "command": "npx",
  "args": ["-y", "@0xlimao/memos-mcp-server"]
}

// With user advanced tools
{
  "command": "npx",
  "args": ["-y", "@0xlimao/memos-mcp-server", "--user-tools"]
}

// With admin tools
{
  "command": "npx",
  "args": ["-y", "@0xlimao/memos-mcp-server", "--admin-tools"]
}

// All tools
{
  "command": "npx",
  "args": ["-y", "@0xlimao/memos-mcp-server", "--full-tools"]
}

Configuration File Location

Instance configurations are stored at:

• macOS/Linux: ~/.config/memos-mcp/instances.json
• Windows: %APPDATA%\memos-mcp\instances.json

Available Tools

Tier 1: Core Tools (Default)

| Tool | Description | |------|-------------| | connect_instance | Connect to a new Memos instance | | disconnect_instance | Remove a connected instance | | list_instances | List all connected instances | | list_memos | List memos with optional filtering | | get_memo | Get a specific memo by ID | | create_memo | Create a new memo | | update_memo | Update an existing memo | | delete_memo | Delete a memo | | list_tags | List all tags | | list_shortcuts | List saved shortcuts | | create_shortcut | Create a new shortcut | | update_shortcut | Update a shortcut | | delete_shortcut | Delete a shortcut | | list_attachments | List attachments | | upload_attachment | Upload a new attachment | | delete_attachment | Delete an attachment |

Tier 2: User Advanced Tools (--user-tools)

| Tool | Description | |------|-------------| | list_personal_access_tokens | List PATs for a user | | create_personal_access_token | Create a new PAT | | delete_personal_access_token | Delete a PAT | | list_webhooks | List webhooks for a user | | create_webhook | Create a new webhook | | update_webhook | Update a webhook | | delete_webhook | Delete a webhook | | get_user_setting | Get user settings | | update_user_setting | Update user settings | | list_user_settings | List all user settings | | list_notifications | List user notifications | | update_notification | Update a notification | | delete_notification | Delete a notification |

Tier 3: Admin Tools (--admin-tools)

| Tool | Description | |------|-------------| | list_users | List all users | | get_user | Get a specific user by ID or username | | create_user | Create a new user | | update_user | Update a user | | delete_user | Delete a user | | get_instance_profile | Get instance information | | get_instance_setting | Get instance settings | | update_instance_setting | Update instance settings | | list_activities | List activities | | get_activity | Get a specific activity |

Examples

Connecting to a Memos Instance

"Connect to my Memos instance at https://memos.example.com with the API key abc123"

The AI will use the connect_instance tool to save the connection:

• Host: https://memos.example.com
• Name: A friendly name (e.g., personal, work)
• API Key: Your access token from Memos → Settings → My Account → Access Tokens

Searching Across All Instances

"Find all memos containing 'project ideas' in all my memos instances"

The server will query all connected instances and return matching results.

Querying a Specific Instance

"Create a new memo in my work-memos instance about the meeting today"

The server will create the memo only in the specified instance.

Using Filters

"List all archived memos with the #important tag"

The server supports CEL filter expressions for advanced queries.

Development

# Clone the repository
git clone https://github.com/flyinglimao/mcp-server-memos.git
cd mcp-server-memos

# Install dependencies
pnpm install

# Run in development mode
pnpm run dev

# Run tests
pnpm test

# Lint code
pnpm run lint

# Format code
pnpm run format

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.