MCP Server

The Mem-Brain MCP server runs locally and exposes your memory as callable tools over the Model Context Protocol. Any MCP-capable client — Cursor, Claude Code, Agno — can then callsearch_memories, add_memory, and the rest automatically.

Install

Two options — pick whichever you prefer:

Option A — uvx (no install needed)

uvx mem-brain-mcp

Option B — pip

pip install mem-brain-mcp
mem-brain-mcp

The server starts on http://localhost:8100 by default. You can verify it's running:

curl http://localhost:8100/health

Connect your client

Cursor

Add this to ~/.cursor/mcp.json. Replace mb_live_xxx with your real API key.

~/.cursor/mcp.json

{
  "mcpServers": {
    "mem-brain": {
      "url": "http://localhost:8100/mcp",
      "headers": {
        "X-API-Key": "mb_live_xxx"
      }
    }
  }
}

Claude Code

claude mcp add mem-brain \
  --scope user \
  --url http://localhost:8100/mcp \
  --header "X-API-Key: mb_live_xxx"

Claude Desktop

claude_desktop_config.json

{
  "mcpServers": {
    "mem-brain": {
      "url": "http://localhost:8100/mcp",
      "headers": {
        "X-API-Key": "mb_live_xxx"
      }
    }
  }
}

The MCP server is stateless — it proxies every tool call to the Mem-Brain API with your API key. You can run one server and share it across clients by passing different keys per client.

Mem-Brain memory writes are async at the REST layer, but the MCP client polls the ingest job for you. From the MCP tool perspective, add_memory(...) still behaves like a normal blocking tool call.

Available tools

Tool	What it does
`add_memory(content, tags?, category?, ingestion_scope?)`	Store a new memory; optional ingest-time tag scope for merge/link candidates
`search_memories(query, k?, keyword_filter?, scope_regex?, response_format?)`	Semantic search; use either `keyword_filter` or `scope_regex`, not both
`traverse_graph(start_memory_id, query, ...)`	Semantic graph traversal along edge descriptions
`get_memories(memory_ids)`	Fetch specific memories by ID
`delete_memories(memory_id? \| tags? \| category?)`	Delete by ID, tag, or category
`get_stats()`	Count and metadata about your memory store
`get_agent_instructions()`	Returns a prompt snippet the agent can use as context

Search response formats

The response_format parameter on search_memories controls what comes back:

Value	Returns
`raw`	Memory nodes and graph edges
`interpreted`	LLM plain-language summary — best for injecting directly into context
`both`	Summary plus raw evidence

Example — search with interpreted response

search_memories(query="What does the user prefer for their editor?", response_format="interpreted")

Environment variables

Variable	Default	Description
`API_BASE_URL`	hosted Railway URL	URL of your Mem-Brain API
`MEMBRAIN_API_KEY`	—	Fallback key for single-user local runs. Overridden by the per-request header.
`MCP_SERVER_PORT`	8100	Port the MCP server listens on
`LOG_LEVEL`	`INFO`	Set to `DEBUG` to log every tool call

Troubleshooting

Tools not appearing in Cursor: restart Cursor after editing mcp.json and check that the server is running.
401 errors: make sure your X-API-Key header is present and the key starts with mb_live_.
Server not responding: run curl http://localhost:8100/health — if that fails the server isn't up yet.
Silent failures: set LOG_LEVEL=DEBUG and restart to see full request/response logs.