mcp-server-zep-cloud

MCP Server for Zep Cloud

Give Claude and Codex long-term memory via Zep Cloud — store conversations, search a knowledge graph, and recall context across sessions.

Prerequisites

Get a free Zep Cloud API key at app.getzep.com.

Quick Start

Claude Code (CLI)

claude mcp add zep-cloud \
  -e ZEP_API_KEY=your-key \
  -e ZEP_DEFAULT_USER_ID=your-user-id \
  -- uvx --from git+https://github.com/fshamim/mcp-server-zep-cloud mcp-server-zep-cloud

Codex (CLI + Desktop)

Codex uses ~/.codex/config.toml for both CLI and Desktop.

codex mcp add zep-cloud \
  --env ZEP_API_KEY=your-key \
  --env ZEP_DEFAULT_USER_ID=your-user-id \
  -- /opt/homebrew/bin/uvx --from git+https://github.com/fshamim/mcp-server-zep-cloud mcp-server-zep-cloud

If the client still shows the old launch command, restart Codex so it reloads MCP config.

If uvx is already on your PATH, you can replace /opt/homebrew/bin/uvx with uvx.

Claude Desktop

Add to your Claude Desktop config file:

• macOS Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "zep-cloud": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/fshamim/mcp-server-zep-cloud",
        "mcp-server-zep-cloud"
      ],
      "env": {
        "ZEP_API_KEY": "your-key",
        "ZEP_DEFAULT_USER_ID": "your-user-id"
      }
    }
  }
}

ZEP_DEFAULT_USER_ID sets the user for all tool calls that don't explicitly pass a user_id. Omit it to fall back to "default_user". Desktop apps don't have a skill system, so this env var is the recommended way to set your identity.

Codex Manual Config (optional)

If you prefer editing Codex config directly:

[mcp_servers.zep-cloud]
command = "/opt/homebrew/bin/uvx"
args = ["--from", "git+https://github.com/fshamim/mcp-server-zep-cloud", "mcp-server-zep-cloud"]

[mcp_servers.zep-cloud.env]
ZEP_API_KEY = "your-key"
ZEP_DEFAULT_USER_ID = "your-user-id"

Setup Script (clone + install)

git clone https://github.com/fshamim/mcp-server-zep-cloud.git
cd mcp-server-zep-cloud
python scripts/install.py

The script installs the package, prompts for your API key, and configures Claude Desktop automatically.

Concepts

Understanding Zep's data model helps you use the tools correctly.

• User (user_id): The identity whose memory is being stored — a person, an AI agent, or any entity. Each user has their own isolated knowledge graph.
• Thread (session_id): A conversation or work session within a user's memory. Multiple threads per user are normal; Zep links facts across them automatically via the knowledge graph.
• Graph: Entities and relationships auto-extracted from all of a user's threads. Searchable via zep_search_memory, browsable via zep_get_graph_nodes / zep_get_graph_edges.

Setting the User Identity

Every tool that touches user data accepts an optional user_id argument. There are three ways to set it, applied in this priority order (highest wins):

1. Per tool call (any client)

Pass user_id directly in the tool call. This overrides everything else for that single call:

zep_store_memory(session_id="s1", content="...", user_id="alice")

2. Per session — Claude Code CLI only

Run the /zep-context skill at the start of a session. Claude will pass that user_id to every Zep tool call for the rest of the conversation:

/zep-context fshamim

This overrides ZEP_DEFAULT_USER_ID for the session, but individual tool calls can still override it further.

3. Server default — all clients

Set ZEP_DEFAULT_USER_ID as an environment variable when starting the server. Every tool call that doesn't explicitly pass a user_id will use this value. Falls back to "default_user" if not set.

Claude Desktop — set it in your config JSON (desktop apps have no skill system, so env vars are the recommended default):

"env": {
  "ZEP_API_KEY": "your-key",
  "ZEP_DEFAULT_USER_ID": "fshamim"
}

Codex CLI / Codex Desktop — set it in ~/.codex/config.toml (or use codex mcp add --env ...):

[mcp_servers.zep-cloud.env]
ZEP_API_KEY = "your-key"
ZEP_DEFAULT_USER_ID = "fshamim"

Claude Code — pass it when adding the server:

-e ZEP_DEFAULT_USER_ID=fshamim

Codex CLI — pass it when adding the server:

--env ZEP_DEFAULT_USER_ID=fshamim

Even with ZEP_DEFAULT_USER_ID set, you or Claude can still address a different user at any time by passing user_id explicitly in a tool call. The desktop apps support this — just ask Claude to use a specific user when storing or retrieving memory.

Troubleshooting

Codex: MCP startup failed: No such file or directory

Common causes:

• -e flags were accidentally put inside args instead of using Codex --env.
• uvx isn't available on PATH for the host app process.

Fix:

codex mcp remove zep-cloud
codex mcp add zep-cloud \
  --env ZEP_API_KEY=your-key \
  --env ZEP_DEFAULT_USER_ID=your-user-id \
  -- /opt/homebrew/bin/uvx --from git+https://github.com/fshamim/mcp-server-zep-cloud mcp-server-zep-cloud

Local dev: ImportError: cannot import name 'Zep' from 'zep_cloud'

Your environment likely has an older zep-cloud package. Reinstall from pyproject.toml constraints:

pip install -e .

Verify the server quickly

python tests/test_server_tools.py
# requires ZEP_API_KEY in env
python tests/test_v3_compatibility.py

Claude Code Integration

Auto-memory → Zep sync (hook)

Claude Code writes notes to memory/*.md files during sessions. The included hook syncs those writes to Zep automatically so they persist in the knowledge graph.

Setup:

1. Set environment variables in .claude/settings.local.json (gitignored, keeps credentials private):

{
  "env": {
    "ZEP_API_KEY": "your-key-here",
    "ZEP_USER_ID": "your-user-id-here"
  }
}

2. Enable the hook by copying the hook config from .claude/settings.json into your local settings, or configure it globally in ~/.claude/settings.json.

3. Ensure zep-cloud is importable in your Python environment:

pip install zep-cloud
# or, if the server is already installed:
pip install -e .

How it works: After every Write or Edit tool call that touches a memory/*.md file, hooks/sync_memory_to_zep.py runs asynchronously. It reads the file content and stores it as a system message in the thread claude_code_memory_{ZEP_USER_ID}. The hook exits silently if ZEP_API_KEY or ZEP_USER_ID is not set, so it never interferes with normal Claude Code operation.

Available Tools

All tools that operate on user-specific data accept an optional user_id parameter (defaults to "default_user").

Docker

docker build -t mcp-server-zep-cloud .
docker run -e ZEP_API_KEY="your-key" mcp-server-zep-cloud

Development

Project Structure

core/
  run_server.py          — Entry point, runs asyncio event loop
  zep_cloud_server.py    — MCP server with 7 tools, stdio transport
  zep_cloud_client.py    — API client wrapping zep-cloud SDK v3
config/
  requirements.txt       — Dependencies (for manual/Smithery installs)
  .env.example           — Template for environment variables
scripts/
  install.py             — Automated setup script
tests/
  test_server_tools.py   — Unit tests (no API key needed)
  test_v3_compatibility.py — Integration tests (requires ZEP_API_KEY)
pyproject.toml           — Package metadata and build config

Install for Development

pip install -e .

Run the Server

mcp-server-zep-cloud          # via console entry point
python core/run_server.py     # direct execution

Run Tests

python tests/test_server_tools.py        # Unit tests (no API key needed)
python tests/test_v3_compatibility.py    # Integration tests (requires ZEP_API_KEY)

License

MIT — see LICENSE.