# MCP Server for Zep Cloud

Give Claude and Codex long-term memory via [Zep Cloud](https://www.getzep.com/) — store conversations, search a knowledge graph, and recall context across sessions.

## Prerequisites

Get a free Zep Cloud API key at [app.getzep.com](https://app.getzep.com/).

## Quick Start

### Claude Code (CLI)

```bash
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.

```bash
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`

```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:

```toml
[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)

```bash
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):

```json
"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 ...`):

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

**Claude Code** — pass it when adding the server:

```bash
-e ZEP_DEFAULT_USER_ID=fshamim
```

**Codex CLI** — pass it when adding the server:

```bash
--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:

```bash
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:

```bash
pip install -e .
```

### Verify the server quickly

```bash
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):

```json
{
  "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:

```bash
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"`).

| Tool | Description |
|------|-------------|
| `zep_store_memory` | Store content in a memory thread (auto-creates user + thread) |
| `zep_get_memory` | Retrieve messages from a thread with pagination and role filtering |
| `zep_search_memory` | Semantic search across a user's knowledge graph |
| `zep_get_graph_nodes` | List all entities (nodes) in a user's knowledge graph |
| `zep_get_graph_edges` | List all relationships (edges/facts) in a user's knowledge graph |
| `zep_get_node_details` | Get detailed info about a node including edges and episodes |
| `zep_get_thread_context` | Cross-thread context retrieval from a user's past conversations |

## Docker

```bash
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

```bash
pip install -e .
```

### Run the Server

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

### Run Tests

```bash
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](LICENSE).