io.github.Lyellr88/marm-mcp-server

"agent" refers to claude, gemini (agy), grok, qwen, or any MCP client. Codex uses --url instead of --transport to add MCP tools.

pip install marm-mcp-server
marm-memory start
# Stuck on client setup? Open a Q&A thread: https://github.com/Lyellr88/marm-memory/discussions
# most agents use this --transport command
"agent" mcp add --transport http marm-memory http://localhost:8001/mcp
codex mcp add marm-memory --url http://localhost:8001/mcp

Default pip/local startup is zero-config: MARM binds to localhost and does not require a key unless you expose it with SERVER_HOST=0.0.0.0.

pip install marm-mcp-server
python -m marm_mcp_server.server_stdio
# most agents use this --transport command
"agent" mcp add --transport stdio marm-memory-stdio marm-mcp-stdio
codex mcp add marm-memory-stdio -- marm-mcp-stdio

Replace marm-mcp-stdio with python -m marm_mcp_server.server_stdio if using a virtualenv or a path-based setup. Works with Claude Code, Cursor, VS Code, Qwen, and Antigravity. STDIO stays a single local process with no port and no API key, and exposes the same 16 tools as HTTP.

Use HTTP when multiple agents need to share one live MARM server. STDIO is still best for private single-agent use because each client owns its own local process.

# HTTP shared server, normal multi-agent use
marm-memory start --profile swarm

# HTTP shared server, heavier private swarm
marm-memory start --profile swarm-max

# HTTP trusted private lab/server, rate limiting disabled
marm-memory start --profile trusted

# STDIO remains keyless/private and does not use swarm flags
marm-mcp-stdio

Docker HTTP requires an API key because it exposes MARM as a network server; STDIO stays local to the client process and does not need one.

If you installed MARM through pip, the product CLI can safely preview or run the same setup. It uses a loopback port by default, preserves ~/.marm, stores the generated key in ~/.marm/.env rather than shell history, and refuses to replace an existing container.

marm-memory docker command                 # preview the exact HTTP command
marm-memory docker run                     # create the managed HTTP container
marm-memory docker stdio-command           # print a Docker STDIO client command
marm-memory docker status
marm-memory docker logs --follow
marm-memory docker stop

# Optional: mount repositories read-only for code indexing.
marm-memory docker run --repo /absolute/path/to/repository

# Optional: preview or explicitly write a Compose configuration.
marm-memory docker compose
marm-memory docker compose --yes

The HTTP run, command, and compose commands accept the same operational flags:

For example:

# Shared local server with a custom data path and two repositories for indexing.
marm-memory docker command \
  --profile swarm \
  --data-dir /srv/marm-data \
  --repo /srv/projects/api \
  --repo /srv/projects/web

# Execute the reviewed command, pulling the image first.
marm-memory docker run --profile swarm --data-dir /srv/marm-data --pull

Docker STDIO is separate from Docker HTTP: marm-memory docker stdio-command uses docker run -i --rm, has no port and no bearer key, but still mounts the data directory so SQLite memory persists after the short-lived container exits. Use --data-dir and --tag with that command when needed. There are no separate docker key or docker mount commands; --env-file and --data-dir make those choices explicit in the generated HTTP command.

marm-memory docker pull only downloads an image. marm-memory docker maintenance embeddings migrate runs against the same data mount and refuses while the managed HTTP container is running. The helper is available only with the pip-installed marm-memory command; Docker-only users can use the raw commands below.

# Step 1: generate key (do not add < > around the key)
docker run --rm lyellr88/marm-mcp-server:latest --generate-key

# Step 2: run server
docker pull lyellr88/marm-mcp-server:latest
docker run -d --name marm-mcp-server \
  -p 127.0.0.1:8001:8001 \
  -e SERVER_HOST=0.0.0.0 \
  -e MARM_API_KEY=your-generated-key \
  -v ~/.marm:/home/marm/.marm \
  lyellr88/marm-mcp-server:latest

# Step 3: connect client
"agent" mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

# PowerShell: set this before starting/restarting Codex
$env:MARM_API_KEY="your-generated-key"
codex mcp add marm-memory --url http://localhost:8001/mcp --bearer-token-env-var MARM_API_KEY

# Quick auth smoke test
curl -i -H "Authorization: Bearer $env:MARM_API_KEY" http://127.0.0.1:8001/mcp

--bearer-token-env-var takes the environment variable name, not the raw key. Start or restart Codex from the same shell after setting $env:MARM_API_KEY. For local Docker smoke tests, MARM_API_KEY=test is fine and avoids shell escaping problems; use a generated key for real deployments. A 406 Not Acceptable from the smoke-test GET /mcp means auth reached the MCP endpoint; 401 Unauthorized means the key is missing or mismatched.

# --swarm: write queue on, 200 RPM - recommended for multi-agent shared servers
docker run -d --name marm-mcp-server \
  -p 127.0.0.1:8001:8001 \
  -e SERVER_HOST=0.0.0.0 \
  -e MARM_API_KEY=your-generated-key \
  -v ~/.marm:/home/marm/.marm \
  lyellr88/marm-mcp-server:latest --swarm

Docker graph tools run inside the container, so they cannot see host paths unless you mount them at docker run.

$env:MARM_API_KEY="test"

# The second -v line mounts your repo; adjust the host path to your project
docker run -d --name marm-mcp-server `
  -p 127.0.0.1:8001:8001 `
  -e SERVER_HOST=0.0.0.0 `
  -e MARM_API_KEY=$env:MARM_API_KEY `
  -v ~/.marm:/home/marm/.marm `
  -v C:\Users\lyell\Desktop\marm-memory:/workspace/marm-memory `
  lyellr88/marm-mcp-server:latest

Then index the container path, not the Windows host path:

marm_graph_index(repo_path="/workspace/marm-memory")

Graph tools must use the container path. Mounts cannot be added to an already-running container; stop and restart the container with the repo mount when you want Docker graph indexing.

Docker STDIO includes the same built-in marm-graph tools; no extra image or install step is required.

docker run --rm -i \
  -v ~/.marm:/home/marm/.marm \
  --entrypoint python \
  lyellr88/marm-mcp-server:latest \
  -m marm_mcp_server.server_stdio

• Docker HTTP requires a key; Docker STDIO does not.
• If you get 401, verify key match and client restart after env var changes.
• For full key setup, rotation, and troubleshooting: INSTALL-DOCKER.md

claude mcp add --transport http marm-memory http://localhost:8001/mcp

Claude Code supports HTTP, SSE, and STDIO through claude mcp add; use HTTP for MARM. For STDIO: claude mcp add --transport stdio marm-memory-stdio marm-mcp-stdio.

Add to .vscode/mcp.json in your workspace. Use marm-memory-local for direct Python installs; marm-memory-docker for Docker or exposed/key mode.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "marm-api-key",
      "description": "MARM API Key for Docker or exposed server mode",
      "password": true
    }
  ],
  "servers": {
    "marm-memory-local": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    },
    "marm-memory-docker": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer ${input:marm-api-key}"
      }
    }
  }
}

Open .vscode/mcp.json, click Start above the server you want, then use Copilot Agent or any extension that consumes VS Code's native MCP registry.

Add to .cursor/mcp.json in your workspace. Cursor uses mcpServers, not VS Code's servers root.

{
  "mcpServers": {
    "marm-memory-local": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    },
    "marm-memory-docker": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MARM_API_KEY}"
      }
    }
  }
}

For Docker/key mode, launch Cursor with MARM_API_KEY set in the environment.

The Cursor CLI (agent) reads the same mcp.json files, so a server added for the editor is already available there. Run agent mcp list to check. A server in the global ~/.cursor/mcp.json loads without approval. A server in a project's .cursor/mcp.json asks you to trust the folder and approve it on first use, and headless runs need --trust --approve-mcps. If it lists no servers, look in mcp.json for an entry with an unknown type such as streamable-http: the CLI drops the whole file when one entry fails to parse. Install it with curl https://cursor.com/install -fsS | bash on macOS, Linux and WSL, or irm 'https://cursor.com/install?win32=true' | iex in Windows PowerShell.

Codex uses codex mcp add or TOML config at ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows).

# Direct Python install - no key needed
codex mcp add marm-memory --url http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required (set MARM_API_KEY in your shell first)
codex mcp add marm-memory --url http://localhost:8001/mcp --bearer-token-env-var MARM_API_KEY

[mcp_servers."marm-memory"]
url = "http://localhost:8001/mcp"
enabled = true
bearer_token_env_var = "MARM_API_KEY"

Grok Build (grok), xAI's terminal coding agent, supports STDIO and HTTP MCP servers and reads ~/.grok/config.toml. MARM sets bearer_token_env_var, so the key stays in your environment and never lands in the file.

# Direct Python install - no key needed
grok mcp add --transport http marm-memory http://localhost:8001/mcp

Docker or SERVER_HOST=0.0.0.0 (key required): set MARM_API_KEY, then add this to ~/.grok/config.toml (or .grok/config.toml for one project):

[mcp_servers.marm-memory]
url = "http://localhost:8001/mcp"
bearer_token_env_var = "MARM_API_KEY"

Grok Build also reads MCP servers from ~/.claude.json, .cursor/mcp.json, and project .mcp.json, so MARM may already load if Claude Code or Cursor has it. Run grok mcp list to see what it loaded.

Hermes Agent (hermes) by Nous Research reads MCP servers from mcp_servers in config.yaml: ~/.hermes/config.yaml on macOS and Linux, %LOCALAPPDATA%\hermes\config.yaml on native Windows, or $HERMES_HOME/config.yaml if you set it. It supports STDIO and HTTP and expands ${VAR} in headers, so the key stays in your environment or ~/.hermes/.env and never lands in the file.

# STDIO - no key needed
hermes mcp add marm-memory --command marm-mcp-stdio

# HTTP, direct Python install - no key needed
hermes mcp add marm-memory --url http://localhost:8001/mcp

Docker or SERVER_HOST=0.0.0.0 (key required): set MARM_API_KEY, then add this under mcp_servers in config.yaml:

mcp_servers:
  marm-memory:
    url: "http://localhost:8001/mcp"
    headers:
      Authorization: "Bearer ${MARM_API_KEY}"

Run /reload-mcp in Hermes, or start a new session, to load it.

OpenCode (opencode, installed with npm install -g opencode-ai) reads MCP servers from mcp in opencode.json or opencode.jsonc: ~/.config/opencode/ on every platform including Windows (%USERPROFILE%\.config\opencode), or $XDG_CONFIG_HOME/opencode/ if you set it, and opencode.json in a project root for one project. It supports STDIO (type: local) and HTTP (type: remote) and expands {env:VAR} in headers, so the key stays in your environment and never lands in the file. Remote servers try OAuth by default, so MARM writes oauth: false. OpenCode 2 nests servers under mcp.servers and still reads the layout below, and MARM writes into whichever layout the file already uses. Connecting from the Console rewrites the file as plain JSON, so comments in a .jsonc file are not kept, and the original is saved beside it as .marm-backup. Start a new OpenCode session to load it, and run opencode mcp list to check.

STDIO, no key needed:

{
  "mcp": {
    "marm-memory": {
      "type": "local",
      "command": ["marm-mcp-stdio"]
    }
  }
}

HTTP, direct Python install (no key needed):

{
  "mcp": {
    "marm-memory": {
      "type": "remote",
      "url": "http://localhost:8001/mcp",
      "oauth": false
    }
  }
}

Docker or SERVER_HOST=0.0.0.0 (key required): set MARM_API_KEY, then add the same HTTP entry with a header:

{
  "mcp": {
    "marm-memory": {
      "type": "remote",
      "url": "http://localhost:8001/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MARM_API_KEY}"
      }
    }
  }
}

Devin CLI (devin) and the Devin Local agent in Devin Desktop, the IDE formerly called Windsurf, read MCP servers from the same mcp_config.json: ~/.config/devin/mcp_config.json on macOS and Linux (or $XDG_CONFIG_HOME/devin/mcp_config.json if you set it), %APPDATA%\devin\mcp_config.json on Windows. Connecting once covers both. The older Cascade agent in Devin Desktop keeps its MCP servers in its own file under ~/.codeium, which MARM does not write. Devin CLI v3000.3 or later reads this dedicated file, and older builds keep mcpServers in config.json and migrate it on startup. devin mcp add saves to a gitignored project file unless you pass -s user.

# STDIO - no key needed
devin mcp add -s user marm-memory -- marm-mcp-stdio

# HTTP, direct Python install - no key needed
devin mcp add -s user marm-memory http://localhost:8001/mcp

Docker or SERVER_HOST=0.0.0.0 (key required): MARM has not confirmed that Devin expands environment variables in headers, so use STDIO, or add the key by hand under mcpServers in that file:

{
  "mcpServers": {
    "marm-memory": {
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

Zed reads MCP servers from context_servers in its user settings.json: ~/.config/zed/settings.json on macOS and Linux (or $XDG_CONFIG_HOME/zed/settings.json on Linux), %APPDATA%\Zed\settings.json on Windows. Run zed: open settings file from the command palette to open it. Zed has no add command, and MARM has not confirmed that Zed expands environment variables in headers, so keyed setups use STDIO. Connecting from the Console edits only the marm-memory entry as text, so comments and the rest of your settings stay as they were, and it restores the file if anything else changed. Zed lists the server under Settings, AI, MCP Servers, with a green dot when it is running. Zed's own agent reads the MARM skill from ~/.agents/skills once you install it from the Console.

STDIO, no key needed:

{
  "context_servers": {
    "marm-memory": {
      "command": "marm-mcp-stdio",
      "args": []
    }
  }
}

HTTP, direct Python install (no key needed):

{
  "context_servers": {
    "marm-memory": {
      "url": "http://localhost:8001/mcp"
    }
  }
}

Docker or SERVER_HOST=0.0.0.0 (key required): use STDIO, or paste the key into the entry by hand. Zed keeps it as plain text in settings.json:

{
  "context_servers": {
    "marm-memory": {
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

Cline CLI (cline, installed with npm install -g cline) reads MCP servers from ~/.cline/data/settings/cline_mcp_settings.json, the same file the Cline extensions in VS Code and JetBrains use (%USERPROFILE%\.cline on Windows, or $CLINE_DATA_DIR/settings if you set it). Cline's own MCP page still says ~/.cline/mcp.json, but the CLI never reads that file. HTTP entries need "type": "streamableHttp": leaving type out selects the legacy SSE transport. The extensions in VS Code and JetBrains show the server in their MCP Servers panel. Cline 4.x or later shares this file and moves an older file from VS Code's extension storage into it on first launch. Older builds keep reading their own file, so upgrade Cline first.

# STDIO - no key needed
cline mcp install marm-memory --yes -- marm-mcp-stdio

# HTTP, direct Python install - no key needed
cline mcp install marm-memory --yes --transport http http://localhost:8001/mcp

Docker or SERVER_HOST=0.0.0.0 (key required): MARM has not confirmed that Cline CLI expands environment variables in headers, so use STDIO, or add the key by hand under mcpServers in that file:

{
  "mcpServers": {
    "marm-memory": {
      "type": "streamableHttp",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

Antigravity CLI (agy) replaced Gemini CLI in June 2026. It supports STDIO and HTTP MCP servers. Use HTTP for MARM. The Antigravity IDE and 2.0 app read this same file (in the IDE, open "..." then MCP Servers, then Manage MCP Servers). Antigravity 2.x or later reads it. Older IDE builds used ~/.gemini/antigravity/mcp_config.json, and MARM writes that file only when it is the only one present.

# Direct Python install - no key needed
agy mcp add marm-memory --type http http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required
agy mcp add marm-memory --type http http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

Equivalent ~/.gemini/config/mcp_config.json (user scope) or project .agents/mcp_config.json. Antigravity reads serverUrl, not url or httpUrl, and does not expand ${VAR} in this file, so paste the real key:

{
  "mcpServers": {
    "marm-memory": {
      "serverUrl": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

# Direct Python install - no key needed
qwen mcp add --transport http marm-memory http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required
qwen mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

Equivalent .qwen/settings.json (project) or ~/.qwen/settings.json (user):

{
  "mcpServers": {
    "marm-memory": {
      "httpUrl": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

The Grok app (grok.com, iOS, Android) supports custom MCP servers: open grok.com/connectors, click New Connector, choose Custom, and enter your MARM URL. The xAI API supports Remote MCP Tools over Streamable HTTP or SSE only.

Both run on xAI's infrastructure, so localhost will not work. Expose MARM behind HTTPS (a tunnel or your own domain) and set MARM_API_KEY. MARM has not been tested through the app's connector form. For the API, send this tool payload:

{
  "type": "mcp",
  "server_url": "https://your-marm-domain.example.com/mcp",
  "server_label": "marm-memory",
  "authorization": "Bearer your-generated-key"
}

Requirements

• Python: 3.10 or higher
• SQLite3: Included with Python (no separate install needed)
• Storage: ~100MB minimum for initial setup, scales with memory database size
• RAM: 512MB minimum (varies by concurrent clients and database size)
• OS: Windows, macOS, Linux

Data location

• Location: ~/.marm/ (Linux/macOS) or %USERPROFILE%\.marm\ (Windows)
• Contents: SQLite database with all memories, sessions, and notebooks; the concept graph lives in its own ~/.marm/index/ database
• Backup: Copy the entire ~/.marm/ directory to preserve all data
• Privacy: Everything stays on your machine, no cloud sync or external storage
• Knows which memories go unused: each memory records how often recall returned it and when, and the Console lists cold memories (GET /api/memories/cold?days=30) so old, never-recalled entries can be reviewed. Counting never slows or fails a recall and does not change ranking
• Credentials are redacted before storage: API keys, tokens, private keys and NAME=value secrets (a metadata field is read with its name, and a quoted value may hold spaces) in anything written to memory, the log, the notebook, or a review queue, and in every prompt sent to a local model, are replaced with [redacted:<kind>]; names and templates stay. A write that redacted something says so in its response as redacted: {count, kinds}, never the values. An identifier holding a credential (a session, project or platform name, a Session: marker, a notebook entry name) is refused rather than redacted, because a renamed identifier could not be looked up again. This is high-precision protection for common credential formats, not a guarantee that every secret is caught, and it applies to new writes only: existing data is not scanned or rewritten

Verify installation

Use the MCP server health endpoint for the fastest live check:

curl http://localhost:8001/health

Expected output includes server version, feature availability (semantic search status), database connection status, and service health status.