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.