MCP server for AI assistants

The Memory Book MCP server exposes read-access book operations to an AI assistant (Claude Desktop, or any Model Context Protocol client) so it can list your books and read approved memories on your behalf. It is the same data, the same auth, and the same scope as the REST API, surfaced over MCP instead of HTTP.

Status: pre-release. The tool surface is stable but unannounced. Get in touch before you build on it so we can flag any in-flight changes.

How it works (and how it differs from the REST API)

Unlike the REST API, the MCP server is not a hosted network endpoint you point a client at over the internet. It is a stdio process that runs next to the Memory Book application and its database: it boots Django and reads the database directly. You (or whoever operates the deployment) run it locally, hand it one API key, and connect a local MCP client to that process over stdio.

Practically, that means the MCP server is for people who can run Memory Book's code beside the database: the platform operator, a self-hosted deployment, or a developer working against a local copy. A hosted, remote MCP transport is a possible future addition; today it is stdio only. If you are a book owner who wants MCP access and you do not run the code yourself, email [email protected].

Prerequisites

  • A plan with API access. The MCP server is gated by the exact same api_access plan feature as the REST API. Books on a plan without that feature are invisible to the server (they do not appear in list_books, and asking for one by slug returns not_found). See plans and pricing.
  • Owner or admin role on the books you want to read. The server cannot see books where your account is only a contributor.
  • An API key. The server authenticates with one Memory Book API key, the same key type the REST API uses. Mint one with the browser flow in API getting started, or have an operator run manage.py create_api_key. The key carries one user's access; the MCP client sees exactly what that user can read.
  • A checkout of the Memory Book code with database access, since the server runs co-located with the app (see above).

1. Install the MCP SDK

The official mcp SDK is deliberately not a dependency of the web application, so the live site never ships it. Install it only in the environment where you run the server:

uv add mcp
# or, with pip:
pip install mcp

If the SDK is missing when you start the server, it exits with install guidance rather than failing obscurely.

2. Run the server

The server reads its API key from the MCP_API_KEY environment variable and speaks MCP over stdio:

DJANGO_SETTINGS_MODULE=config.settings.production \
MCP_API_KEY=omb_live_... \
uv run python -m apps.mcp.server

Variables explained:

  • MCP_API_KEY: the plaintext API key (including its omb_live_ prefix). This single key defines the server's entire scope.
  • DJANGO_SETTINGS_MODULE: point at the settings module whose database holds the books you want to read (config.settings.production against the production database, or a local settings module against a dev database).

You normally do not run this command by hand. An MCP client launches it for you (next section) and talks to it over stdin/stdout.

3. Connect an MCP client

Point your MCP client at the run command. For Claude Desktop, add an entry to its mcpServers config (Settings, then Developer, then Edit Config):

{
  "mcpServers": {
    "memorybook": {
      "command": "uv",
      "args": ["run", "python", "-m", "apps.mcp.server"],
      "cwd": "/path/to/memorybook",
      "env": {
        "DJANGO_SETTINGS_MODULE": "config.settings.production",
        "MCP_API_KEY": "omb_live_..."
      }
    }
  }
}

Fields explained:

  • command plus args: how the client launches the server process. Use the same invocation you would run in the shell.
  • cwd: the Memory Book checkout, so uv resolves the right virtual environment and Django finds your settings.
  • env.MCP_API_KEY: the key. Treat this config file as a secret; anyone who can read it has the key's access.

Restart the client. The three tools below appear under the memorybook server, and the assistant can call them when you ask about your books.

Available tools

Three read-access tools (none of them write). Each returns a plain JSON object. Auth and authorization failures come back as {"error": "<code>", "message": "..."} rather than raising, so the assistant can surface them without crashing the session.

list_books()

The books this key can read: owner or admin role, on a plan with API access.

{
  "books": [
    {
      "slug": "grandma-stories",
      "title": "Grandma stories",
      "lifecycle_state": "active",
      "visibility": "public"
    }
  ]
}

get_book(slug)

One book's metadata.

{
  "slug": "grandma-stories",
  "title": "Grandma stories",
  "description": "Stories for Grandma's 80th.",
  "lifecycle_state": "active",
  "visibility": "public"
}

list_submissions(slug, limit=50)

A book's approved memories, newest first. limit is clamped to the range 1 to 200 (default 50). Each memory's text is truncated to 2000 characters.

{
  "submissions": [
    {
      "id": "01HG4M3R8N2X...",
      "contributor_name": "Marcus",
      "created_at": "2026-05-17T12:34:56Z",
      "text": "Visiting Grandma in 2003 was when I learned to make her bread."
    }
  ]
}

Scope and privacy

The server can never see more than a correctly-scoped REST client, because it runs through the same authorization policy:

  • Read access only. There is no tool that creates, edits, or deletes anything. The assistant cannot submit memories, moderate, or change settings through MCP.
  • Plan-gated. A book whose plan lacks api_access is invisible: absent from list_books, and get_book / list_submissions for it return not_found.
  • Role-gated. Only books where the key's user is owner or admin are reachable.
  • Privacy-respecting. list_submissions returns only approved memories, and applies the same visibility rules as every other surface: private memories are shown only to the owner (or staff), never to a non-owner admin.
  • No slug enumeration. A book you cannot read returns the same not_found as a book that does not exist, so a key cannot probe which slugs exist platform-wide.
  • Deactivation closes the window. A revoked or expired key, or a deactivated user, is rejected the same as on the REST API.

Errors

Two error shapes you will encounter:

  • {"error": "unauthorized", "message": "Invalid or expired API key."}: the MCP_API_KEY is wrong, revoked, expired, or its user is deactivated.
  • {"error": "not_found", "message": "No book '<slug>'."}: the slug does not exist, OR it exists but this key cannot read it (no membership, or the plan lacks api_access). The two cases are intentionally indistinguishable.

Next steps

  • Need to mint a key first? See API getting started.
  • Want write access or remote (HTTP) access? Use the REST API; the MCP server is read-access and local by design.
  • Questions or a request for a hosted MCP transport: [email protected].

Ready to try it? Create your free memory book