MCP Integration Guide

The smart-memory-mcp package is an MCP server that exposes SmartMemory operations to MCP-compatible clients (Claude Desktop, Cursor, Maya, custom agents). It is a separate package from smart-memory-core and ships its own tool catalogue.

For the full tool catalogue with signatures, see api/tools.md.

Install

pip install smartmemory-mcp

The console script is smartmemory-mcp (registered in pyproject.toml):

smartmemory-mcp                    # stdio transport (default)
smartmemory-mcp --http             # HTTP transport on 0.0.0.0:8011
smartmemory-mcp --http --port 9100 # custom HTTP port

You can also invoke the module directly: python -m smartmemory_mcp.

Backends

The server can route every tool call to one of two backends; the choice is independent of the tier model.

Backend	When	How it's selected
Local	You have `smartmemory` (and FalkorDB / Redis) installed locally.	Default. Uses the in-process `SmartMemory` API.
Remote	You want to talk to a hosted `smart-memory-service` deployment.	`smartmemory setup --mode remote` (from the desktop app), or set `SMARTMEMORY_API_KEY` and ensure `smartmemory_app` config has `mode=remote`.

whoami() reports the active backend.

Tiers

Tools are registered into three tiers at server startup. Restarting the server is required after any tier-changing event (login, env var change).

Tier	Tools (cumulative)	Unlock
FREE	13	Default — no auth required
PRO	58 (+45)	`login(api_key)` (or `SMARTMEMORY_API_KEY` env)
PRO+	89 (+31)	PRO and `SMARTMEMORY_MCP_FULL_TOOLS=true`

FREE

login, whoami, switch_team, memory_ingest, memory_search, memory_recall (deprecated), get_working_context, memory_get, memory_export, memory_import, memory_migrate, memory_auto, memory_feedback.

PRO

PRO unlocks PRO-tier memory_* (CRUD: memory_add, memory_update, memory_delete, memory_clear, memory_list, memory_stats, memory_distill, memory_ingest_conversation, memory_search_advanced, memory_search_by_metadata) and the full decisions, code indexing, anchors, plans / failure recall, agent profiles, and structured ingestion suites.

PRO+

PRO+ adds reasoning, evolution, insights, dev workflow, and zettelkasten suites.

See api/tools.md for the complete per-tier list with signatures.

Authentication

Three sources are checked in order — the first non-empty value wins:

SMARTMEMORY_API_KEY environment variable.
The smartmemory_app desktop keyring (if installed).
The fallback file ~/.config/smartmemory/.api_key (written by the login tool).

Calling the login tool stores the key into the file fallback and validates it against the API. The server only re-reads credentials at startup, so:

restart the MCP server after login()

is mandatory.

switch_team(team_id) writes the new team ID into the smartmemory_app config and likewise requires a restart. Without the desktop app installed, set SMARTMEMORY_TEAM_ID instead.

Client configuration

Claude Desktop / Cursor

In the MCP client's config file (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "smartmemory": {
      "command": "smartmemory-mcp",
      "env": {
        "SMARTMEMORY_API_KEY": "sm_live_...",
        "SMARTMEMORY_MCP_FULL_TOOLS": "true"
      }
    }
  }
}

HTTP transport

For multi-process deployments or browser clients, run in HTTP mode:

smartmemory-mcp --http --port 8011

Then point your MCP client at http://localhost:8011.

Calling a tool

Standard MCP tools/call:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memory_search",
    "arguments": { "query": "auth caching", "top_k": 5, "multi_hop": true }
  }
}

All tools return strings, except get_working_context which returns a structured surfacing-response dict.

Service-embedded MCP

A second MCP surface ships inside smart-memory-service at smart-memory-service/smartmemory_mcp/. It re-exposes a subset of the same tools (memory CRUD, decisions, anchors, plans, code, structured, evolution, reasoning, insights, agent, plus a graph_tools module) through the API service's auth layer. It is registered separately from the standalone smartmemory-mcp server and inherits its lifecycle from the FastAPI app — see smart-memory-service for deployment.

Troubleshooting

PRO tools missing after login — restart the MCP server. Tier is resolved once at startup.
whoami reports Backend: remote (smartmemory package not installed) — install smartmemory for local backend, or this is expected if you intend remote-only.
Tools time out — for local backend, ensure FalkorDB (9010), Redis (9012), and (for the service backend) MongoDB (9013) are reachable.
Permission warning on ~/.config/smartmemory/.api_key — the loader logs a warning if the file is group/other-readable. chmod 600 it.