# zep-mcp

MCP server for the [Zep Cloud](https://www.getzep.com/) API — a context engineering platform for AI agent memory. Built with [FastMCP](https://github.com/jlowin/fastmcp) and the [zep-cloud](https://pypi.org/project/zep-cloud/) Python SDK.

## 📖 The story

> I originally built this project back in early 2025 when I was just learning how to code. It worked! ...technically. The old version had a fallback client that returned *fake success responses* when the API was down 😅, wrapper scripts for every platform imaginable, and enough redundant code to make future-me cringe.
>
> A year later, I've learned a thing or two. So I burned it all down and rewrote it.
>
> - **Before:** 2 tangled client layers, 8 tools, fallback mode that lied to you, ~4,000 lines  💀
> - **After:** 1 clean server entry point, 13 tools covering the full Zep Cloud API, ~770 lines
>
> Keeping the old git history because it's kinda funny lmao

## Use cases

I use this for my own content — ingesting video scripts and viewer comments into Zep's knowledge graph to understand what I've covered, what my audience cares about, and what I should make next.

**Map your content knowledge graph** — ingest your scripts and audience comments. Zep auto-extracts topics, entities (e.g. people, groups, ideas), and the relationships between them across everything you've published.

![Full knowledge graph built from content scripts and viewer comments](docs/demo-1-graph.png)

**See what topics cluster together** — explore how a specific entity connects to content pieces and topics. Blue nodes are your actual content; the surrounding topics show what themes appear across those videos and what commenters associate with that entity.

![Entity relationship view showing startup connected to content and related topics from comments](docs/demo-2-relationships.png)

**Find content gaps** — query for entities with many topic and entity connections but no linked content nodes. Those are things your audience is already thinking and talking about that you haven't made a video on yet.

![Rich Asians entity with many topic connections but no content nodes — a content gap](docs/demo-3-content-gaps.png)

## Setup

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

Copy `.env.example` to `.env` and fill in your Zep Cloud API key:

```bash
cp .env.example .env
```

Install the pre-commit hook to prevent accidentally committing secrets:

```bash
cp scripts/pre-commit .git/hooks/pre-commit
```

## Run the server

```bash
source venv/bin/activate
python server.py
```

Or with FastMCP dev mode:

```bash
fastmcp dev server.py
```

## Configuration

| Variable | Required | Description |
|----------|----------|-------------|
| `ZEP_API_KEY` | Yes | Zep Cloud API key |
| `ZEP_TOOLSETS` | No | Comma-separated tool groups to enable. Values: `memory`, `admin`. Defaults to `memory,admin` (all tools). |

## Tools

13 tools organized by jobs-to-be-done:

**Memory tools** (`memory`):
- `add_messages` — Add messages to a conversation thread
- `get_context` — Get assembled context block for a user
- `add_graph_data` — Add data to a knowledge graph (text, JSON, message, or triple)
- `search_graph` — Search a knowledge graph for facts, entities, or episodes
- `get_task` — Poll status of an async Zep operation

**Admin tools** (`admin`):
- `manage_user` — User CRUD (create, get, update, delete, list, warm)
- `manage_user_instructions` — Manage user summary instructions
- `manage_thread` — Thread CRUD (create, get, delete, list)
- `manage_graph` — Graph lifecycle (create, get, update, delete, list, clone)
- `manage_graph_structure` — Graph schema, ontology, and custom instructions
- `manage_graph_data` — Node, edge, and episode inspection and management
- `manage_context_templates` — Context template CRUD
- `project_info` — Get current Zep Cloud project info

## Running tests

```bash
source venv/bin/activate
python -m pytest tests/
```

## License

MIT