# Mem0 MCP Server
[](https://pypi.org/project/mem0-mcp-server/) [](LICENSE)
`mem0-mcp-server` wraps the official [Mem0](https://mem0.ai) Memory API as a Model Context Protocol (MCP) server so any MCP-compatible client (Claude Desktop, Cursor, custom agents) can add, search, update, and delete long-term memories.
## Tools
The server exposes the following tools to your LLM:
| Tool | Description |
| --------------------- | --------------------------------------------------------------------------------- |
| `add_memory` | Save text or conversation history (or explicit message objects) for a user/agent. |
| `search_memories` | Semantic search across existing memories (filters + limit supported). |
| `get_memories` | List memories with structured filters and pagination. |
| `get_memory` | Retrieve one memory by its `memory_id`. |
| `update_memory` | Overwrite a memory’s text once the user confirms the `memory_id`. |
| `delete_memory` | Delete a single memory by `memory_id`. |
| `delete_all_memories` | Bulk delete all memories in the confirmed scope (user/agent/app/run). |
| `delete_entities` | Delete a user/agent/app/run entity (and its memories). |
| `list_entities` | Enumerate users/agents/apps/runs stored in Mem0. |
All responses are JSON strings returned directly from the Mem0 API.
## Filter Guidelines
Mem0 filters use JSON with logical operators. Key rules:
- **Don't mix entities in AND**: `{"AND": [{"user_id": "john"}, {"agent_id": "bot"}]}` is invalid
- **Use OR for different entities**: `{"OR": [{"user_id": "john"}, {"agent_id": "bot"}]}` works
- **Default user_id**: Added automatically if not specified
### Quick Examples
```json
// Single user
{"AND": [{"user_id": "john"}]}
// Agent memories only
{"AND": [{"agent_id": "schedule_bot"}]}
// Multiple users
{"AND": [{"user_id": {"in": ["john", "jane"]}}]}
// Cross-entity search
{"OR": [{"user_id": "john"}, {"agent_id": "bot"}]}
// Recent memories
{"AND": [{"user_id": "john"}, {"created_at": {"gte": "2024-01-01"}}]}
```
## Ways to Run
You can run this server in three modes depending on your setup:
- **Local Stdio (Recommended)**: Best for Claude Desktop, Cursor, or local development. No server port management needed.
- **Smithery**: Best for deploying as a hosted HTTP endpoint or using the Smithery platform.
- **Docker**: Best for containerized deployments where you need an HTTP endpoint.
## How to Connect
### Claude Desktop & Cursor (Stdio)
The easiest way to use Mem0 is by letting `uvx` handle the installation. Add this configuration to your `claude_desktop_config.json` or Cursor MCP settings:
```json
{
"mcpServers": {
"mem0": {
"command": "uvx",
"args": ["mem0-mcp-server"],
"env": {
"MEM0_API_KEY": "sk_mem0_...",
"MEM0_DEFAULT_USER_ID": "your-handle"
}
}
}
}
```
### Manual Installation (CLI)
If you prefer installing the package yourself:
```bash
pip install mem0-mcp-server
```
Then run it directly:
```bash
export MEM0_API_KEY="sk_mem0_..."
mem0-mcp-server
```
## Agent Example
This repository includes a standalone agent (powered by Pydantic AI) to test the server interactively.
```bash
# Clone repo & install deps
git clone https://github.com/mem0-ai/mem0-mcp-server.git
cd mem0-mcp-server
pip install -e ".[smithery]"
# Run the agent REPL
export MEM0_API_KEY="sk_mem0_..."
export OPENAI_API_KEY="sk-openai-..."
python example/pydantic_ai_repl.py
```
This launches "Mem0Guide". Try prompts like "search memories for favorite food" to test your API key and memory storage.
## Configuration
### Environment Variables
- `MEM0_API_KEY` (required) – Mem0 platform API key.
- `MEM0_DEFAULT_USER_ID` (optional) – default `user_id` injected into filters and write requests (defaults to `mem0-mcp`).
- `MEM0_MCP_AGENT_MODEL` (optional) – default LLM for the bundled agent example.
### Config Files
For advanced usage (like switching the agent example to use Docker), this repo includes standard MCP config files in the `example/` directory:
- `example/config.json`: Local Stdio (default)
- `example/docker-config.json`: Docker HTTP
Switch configurations for the agent REPL by setting `MEM0_MCP_CONFIG_PATH`.
## Detailed Setup Guides
<details>
<summary><strong>Click to expand: Smithery, Docker, and Troubleshooting</strong></summary>
### 1. Smithery HTTP
To run the HTTP transport with Smithery:
1. `pip install -e ".[smithery]"` (or `pip install "mem0-mcp-server[smithery]"`).
2. Ensure `MEM0_API_KEY` (and optional `MEM0_DEFAULT_USER_ID`) are exported.
3. `uv run smithery dev` for a local endpoint (`http://127.0.0.1:8081/mcp`).
4. Optional: `uv run smithery playground` to open an ngrok tunnel + Smithery web UI.
5. **Testing**: Create a config copying `example/config.json` but changing the entry to `{ "type": "http", "url": "http://127.0.0.1:8081/mcp" }`, then point `MEM0_MCP_CONFIG_PATH` to it before running the agent REPL.
6. **Hosted deploy**: Push to GitHub, connect at [smithery.ai](https://smithery.ai/new), click Deploy.
### 2. Docker HTTP
To containerize the server:
1. Build the image:
```bash
docker build -t mem0-mcp-server .
```
2. Run the container (ensure env vars are passed):
```bash
docker run --rm -e MEM0_API_KEY=sk_mem0_... -p 8081:8081 mem0-mcp-server
```
3. Connect clients using `example/docker-config.json`:
```bash
export MEM0_MCP_CONFIG_PATH="$PWD/example/docker-config.json"
python example/pydantic_ai_repl.py
```
**Troubleshooting Docker:**
- The container must be running **before** HTTP clients connect.
- Ensure `MEM0_API_KEY` is passed via `-e`.
- If clients can't connect, check that port 8081 is forwarded correctly (`-p 8081:8081`) and that the config URL is reachable.
### 3. FAQ / Troubleshooting
- **`RuntimeWarning: 'mem0_mcp_server.server' found in sys.modules…`**: Harmless warning when running the Pydantic AI REPL.
- **`session_config not found in request scope`**: Expected when running outside Smithery; the server falls back to environment variables.
- **Smithery CLI "server reference not found"**: Ensure `[tool.smithery] server = "mem0_mcp_server.server:create_server"` is present in `pyproject.toml`.
</details>
## Development
```bash
uv sync --python 3.11 # optional, installs dev extras and lockfile
uv run --from . mem0-mcp-server # run local checkout via uvx
```
## License
MIT