@0xlimao/memos-mcp-server

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:

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)

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

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

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.