MCP Server

Memos includes a built-in Model Context Protocol (MCP) server, available since v0.27.0. It lets AI assistants such as Claude search, create, and update your memos through a curated set of tools.

The server is part of the main Memos binary — there is nothing extra to install or enable. It runs at:

https://<your-instance>/mcp

Upgrading older MCP clients

Memos 0.30 replaced the earlier MCP implementation with a stateless, tools-only endpoint generated from the OpenAPI schema. Existing clients must use /mcp and the service-prefixed tool names listed below.

The previous prompts, resources, tool-filtering headers, route aliases, and unprefixed tool names are no longer available. Tool failures now use the standard MCP isError result with readable text content.

Connecting a client

The server uses the Streamable HTTP transport. Point any MCP client that supports it at your instance's /mcp endpoint and authenticate with a personal access token as a Bearer credential:

{
  "mcpServers": {
    "memos": {
      "type": "http",
      "url": "https://<your-instance>/mcp",
      "headers": {
        "Authorization": "Bearer <your-personal-access-token>"
      }
    }
  }
}

With Claude Code, the equivalent one-liner is:

claude mcp add --transport http memos https://<your-instance>/mcp \
  --header "Authorization: Bearer <your-personal-access-token>"

Authentication

Tool calls run against the same REST API as the web app, with the same permissions:

• The token identifies you; tools can only see and change what your account can.
• Mutating tools (create, update, delete) require a valid token.
• Public reads may work without a token only when the instance URL is configured, public mode is enabled, and the underlying REST endpoint allows anonymous access.

Create and revoke personal access tokens from your user settings in the app. See API Access.

Available tools

The server exposes a curated, memo-focused toolset:

Each tool maps to an endpoint of the REST API, so request and response shapes match the API reference. Tools carry standard MCP annotations (read-only, destructive, idempotent) so clients can ask for confirmation before destructive actions.

Browser clients and origins

Desktop MCP clients work out of the box. Browser-based clients are subject to an origin check: requests are accepted when the Origin header is absent, matches the instance's own host, or matches the configured instance URL. Anything else is rejected with 403 to protect against DNS rebinding.

Troubleshooting

• 401 / permission errors — the token is missing, expired, or lacks access to the resource. Create a fresh token in your user settings.
• 403 on connect — your client sends an Origin header that doesn't match the instance. Use a desktop client, or set the instance URL so it matches.
• Tool errors — API failures are returned with isError: true and readable text containing the HTTP status and message, so the assistant can react without trying to validate the error as a successful output schema.