Mem0 Custom MCP Server

![License: MIT](https://opensource.org/licenses/MIT) ![Node.js Version](https://nodejs.org/) ![TypeScript](https://www.typescriptlang.org/) ![MCP Protocol](https://modelcontextprotocol.io/)

A custom Model Context Protocol (MCP) server that connects to self-hosted Mem0 API instances. Enables Claude Code to use your own Mem0 deployment for memory management.

Why This Exists

The official @mem0/mcp-server and community @pinkpixel/mem0-mcp packages only support:

Mem0's cloud platform (requires MEM0_API_KEY)
Supabase backend
Local storage

Neither supports connecting to custom self-hosted Mem0 API endpoints.

This custom MCP server bridges that gap by providing a wrapper around your self-hosted Mem0 API.

Features

✅ Connects to self-hosted Mem0 API at custom endpoints
✅ Implements MCP stdio protocol for Claude Code integration
✅ Supports all core Mem0 operations:
add_memory - Store new memories
search_memories - Semantic search through memories
get_memories - Retrieve all memories for a user
delete_memory - Delete specific memories
✅ Environment variable configuration
✅ Full TypeScript implementation with type safety
✅ 120-second timeout for slow Mem0 API responses (handles LLM processing delays)

Installation

From GitHub (Recommended for now)

# Clone the repository
git clone https://github.com/emasoudy/mem0-custom-mcp.git
cd mem0-custom-mcp

# Install dependencies
npm install

# Build the project
npm run build

From npm (Future - when published)

# This will be available after npm publish
npm install -g mem0-custom-mcp

Configuration

The server is configured via environment variables:

MEM0_API_URL - Your Mem0 API endpoint (default: http://localhost:8888)
DEFAULT_USER_ID - Default user ID for memory operations (default: default)

Example configurations:

Local: http://localhost:8888
Docker: http://host.docker.internal:8888
Remote/VPN: http://your-server-ip:8888

Claude Code Configuration

You can configure this MCP server at either user level (available in all projects) or project level (specific project only).

Option 1: Using CLI (Recommended)

User-level (available everywhere): ``bash claude mcp add mem0 \ --scope user \ --command node \ --arg "/absolute/path/to/mem0-custom-mcp/dist/index.js" \ --env MEM0_API_URL=http://localhost:8888 \ --env DEFAULT_USER_ID=default ``

Project-level (specific project only): ``bash cd /path/to/your/project claude mcp add mem0 \ --scope project \ --command node \ --arg "/absolute/path/to/mem0-custom-mcp/dist/index.js" \ --env MEM0_API_URL=http://localhost:8888 \ --env DEFAULT_USER_ID=default ``

Option 2: Manual Configuration

User-level - Edit ~/.claude.json: ``json { "mcpServers": { "mem0": { "type": "stdio", "command": "node", "args": [ "/absolute/path/to/mem0-custom-mcp/dist/index.js" ], "env": { "MEM0_API_URL": "http://localhost:8888", "DEFAULT_USER_ID": "default" } } } } ``

Project-level - Edit .claude.json in your project root: ``json { "projects": { "your-project-path": { "mcpServers": { "mem0": { "type": "stdio", "command": "node", "args": [ "/absolute/path/to/mem0-custom-mcp/dist/index.js" ], "env": { "MEM0_API_URL": "http://localhost:8888", "DEFAULT_USER_ID": "default" } } } } } } ``

Verify installation: ```bash claude mcp list

Should show "mem0" in the list


## Development

- `npm run build` - Compile TypeScript to JavaScript
- `npm run dev` - Build and run the server
- `npm start` - Run the compiled server

## Available Tools

### add_memory

Store a new memory in Mem0.

**Parameters:**
- `content` (required) - The content to store
- `user_id` (optional) - User ID (defaults to env DEFAULT_USER_ID)
- `metadata` (optional) - Additional metadata object

### search_memories

Search memories using semantic search.

**Parameters:**
- `query` (required) - Search query string
- `user_id` (optional) - User ID (defaults to env DEFAULT_USER_ID)
- `limit` (optional) - Maximum results (default: 10)

### get_memories

Retrieve all memories for a user.

**Parameters:**
- `user_id` (optional) - User ID (defaults to env DEFAULT_USER_ID)
- `limit` (optional) - Maximum results (default: 100)

### delete_memory

Delete a specific memory by ID.

**Parameters:**
- `memory_id` (required) - ID of the memory to delete

## Architecture

This MCP server acts as a bridge between Claude Code and your self-hosted Mem0 API instance:

┌─────────────────────────┐ │ Claude Code │ └────────────┬────────────┘ │ MCP stdio protocol │ ┌────────────▼────────────┐ │ mem0-custom-mcp │ ← This MCP server (Node.js) │ (MCP wrapper) │ └────────────┬────────────┘ │ HTTP REST API (localhost:8888 or custom URL) │ ┌────────────▼────────────┐ │ Self-Hosted Mem0 API │ ← Mem0 API server (Python/FastAPI) │ (your-server:8888) │ Handles memory operations └────────────┬────────────┘ │ ┌────┴─────┐ │ │ ┌────▼───┐ ┌──▼──────┐ │PGVector│ │ Neo4j │ ← Databases managed by Mem0 API │(Vector)│ │ (Graph) │ └────────┘ └─────────┘ ```

Flow:

Claude Code calls MCP tools (add_memory, search_memories, etc.)
mem0-custom-mcp receives requests via MCP stdio protocol
mem0-custom-mcp forwards to Mem0 API via HTTP
Mem0 API processes requests and manages PostgreSQL/Neo4j databases
Results flow back through the chain to Claude Code

Note: This server does NOT directly access PostgreSQL or Neo4j. It communicates only with the Mem0 API endpoint, which handles all database operations.

Mem0 API Endpoints Used

This MCP server uses the following Mem0 API endpoints:

POST /v1/memories - Add new memory
Body: {"messages": [{"role": "user", "content": "..."}], "user_id": "...", "metadata": {}}
GET /v1/memories/{user_id} - Get all memories for a user
Path parameter: user_id
POST /v1/memories/search - Search memories with semantic search
Body: {"query": "...", "user_id": "...", "limit": 10}
DELETE /v1/memories/{memory_id} - Delete a specific memory
Path parameter: memory_id

Troubleshooting

Server won't start

Check debug logs in ~/.claude/debug/ for error messages.

Common issues:

Mem0 API not accessible (check VPN connection)
Invalid endpoint URL
Port conflicts

Connection timeout

The MCP server has a built-in 120-second timeout for Mem0 API requests. This accommodates the time needed for:

OpenAI API calls to generate embeddings
LLM processing to extract entities and relationships
Database operations (PostgreSQL + Neo4j)

Typical memory creation takes 30-60 seconds when using GPT-5-mini.

If you need to adjust the timeout, modify src/index.ts line 59: ``typescript const timeoutId = setTimeout(() => controller.abort(), 120000); // 2 minutes ``

Tool errors

Verify your Mem0 API is running: ```bash

For local deployment

curl http://localhost:8888/health

For remote/VPN deployment

curl http://your-server-ip:8888/health ```

Expected response: ``json {"status":"ok","db_connected":true,"stores":{"vector":"postgresql","graph":"neo4j"}} ``

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development

# Clone and setup
git clone https://github.com/emasoudy/mem0-custom-mcp.git
cd mem0-custom-mcp
npm install

# Make changes to src/index.ts
# Build and test
npm run build
npm run dev  # Build and run

Changelog

See CHANGELOG.md for version history.

License

MIT License - see LICENSE for details.

Acknowledgments

Built for the Model Context Protocol
Works with Mem0 self-hosted instances
Designed for Claude Code

mem0-custom-mcp