memos-mcp

A Model Context Protocol (MCP) server for Memos — a self-hosted note-taking service.

中文文档

Enables AI assistants (Claude Code, Claude Desktop, Cursor, etc.) to read and write your memos through a standardized interface.

Setup

Prerequisites

• Node.js >= 18
• A running Memos instance
• A Memos access token (Settings → Access Tokens)

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | MEMOS_URL | Yes | Your Memos instance URL | | MEMOS_TOKEN | Yes | Memos access token | | MEMOS_DEFAULT_VISIBILITY | No | Default visibility for new memos (PRIVATE, PROTECTED, PUBLIC). Defaults to PRIVATE |

Claude Code

claude mcp add --scope user memos -e MEMOS_URL=https://your-memos-instance.com -e MEMOS_TOKEN=your-access-token -- npx -y @chriscurrycc/memos-mcp

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "memos": {
      "command": "npx",
      "args": ["-y", "@chriscurrycc/memos-mcp"],
      "env": {
        "MEMOS_URL": "https://your-memos-instance.com",
        "MEMOS_TOKEN": "your-access-token"
      }
    }
  }
}

With 1Password (recommended)

Store your token securely in 1Password — no plaintext secrets on disk.

1. Save the token to 1Password:

op item create --category=apiCredential --title="memos-api" token=your-access-token "valid from[date]=2026-01-01" "expires[date]=2026-02-01"

2. Configure with op run to inject the token at runtime:

Claude Code:

claude mcp add --scope user memos -e MEMOS_URL=https://your-memos-instance.com -e MEMOS_TOKEN=op://Personal/memos-api/token -- op run --no-masking -- npx -y @chriscurrycc/memos-mcp

Claude Desktop:

{
  "mcpServers": {
    "memos": {
      "command": "op",
      "args": ["run", "--no-masking", "--", "npx", "-y", "@chriscurrycc/memos-mcp"],
      "env": {
        "MEMOS_URL": "https://your-memos-instance.com",
        "MEMOS_TOKEN": "op://Personal/memos-api/token"
      }
    }
  }
}

Tools

Memos

| Tool | Description | |------|-------------| | list_memos | Search and list memos with structured filters (keyword, tags, date range, visibility, pinned, content properties, etc.) | | get_memo | Get a single memo by numeric ID or UID string | | create_memo | Create a new memo with markdown content | | update_memo | Update content, visibility, pin, archive state, with optional preserveUpdateTime | | delete_memo | Permanently delete a memo |

Tags

| Tool | Description | |------|-------------| | list_tags | List tags with usage counts, hierarchy support, and pinned/emoji metadata | | update_tag | Update a tag's pinned status or emoji | | rename_tag | Rename a tag across all memos |

Resources

| Tool | Description | |------|-------------| | list_resources | List all resources (attachments) | | upload_resource | Upload a file (base64 encoded), with optional memo linking | | delete_resource | Delete a resource |

Relations

| Tool | Description | |------|-------------| | list_memo_relations | List memo relations with recursive graph traversal (depth 1-5) | | set_memo_relations | Add or remove REFERENCE relations between memos |

Review

| Tool | Description | |------|-------------| | get_review_memos | Get today's spaced-repetition review batch | | complete_review | Mark the current review batch as completed | | get_on_this_day_memos | Get memos created on this day in previous years, grouped by year | | update_review_setting | Update review preferences (batch size, tag filters) |

Prompts

| Prompt | Description | |--------|-------------| | capture | Quick-save a thought as a memo | | review | Start a guided spaced-repetition review session | | on_this_day | See memos from this day in previous years | | digest | Summarize memo activity for a time period (today/week/month) | | tag_overview | Review your tag system and organization | | relation_graph | Explore the relation graph starting from a memo |

Resources

| URI Template | Description | |-------------|-------------| | memo://memos/{uid} | Get a memo by UID as markdown |

Development

git clone https://github.com/chriscurrycc/memos-mcp.git
cd memos-mcp
pnpm install
pnpm build

# Run in dev mode
MEMOS_URL=http://localhost:5230 MEMOS_TOKEN=your-token pnpm dev

License

MIT