Skip to content

zep-mcp-server

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

zep-mcp-server

README.md

Zep MCP Server (Deprecated)

Deprecated: This MCP server is no longer maintained. Use the official Zep Memory MCP server instead.

A Model Context Protocol (MCP) server for Zep Cloud, providing read-only access to Zep's temporal knowledge graph and memory features.

Features

  • 🔍 Search & Retrieval: Search the knowledge graph, retrieve context, and access conversation history
  • 📊 Graph Exploration: Query nodes, edges, and episodes from the temporal knowledge graph
  • 🔒 Read-Only: Safe, non-destructive operations for AI assistants
  • ⚡ Fast: Built with Go for optimal performance
  • 🎯 MCP-Compatible: Works with Claude Desktop, Cline, and other MCP clients

Tools

The server provides 13 read-only tools:

Core Search & Retrieval

  1. search_graph - Search the knowledge graph with filters, reranking, and scoped search
  2. get_user_context - Retrieve formatted context for a thread (supports custom templates)
  3. get_user - Get user information and metadata
  4. list_threads - List conversation threads for a user

Graph Query

  1. get_user_nodes - Retrieve entity nodes from a user's knowledge graph
  2. get_user_edges - Retrieve relationship edges from a user's knowledge graph
  3. get_episodes - Get episode nodes (temporal data ingestion events)

Detail Retrieval

  1. get_thread_messages - Retrieve messages from a conversation thread
  2. get_node - Get a specific node by UUID
  3. get_edge - Get a specific edge by UUID
  4. get_episode - Get a specific episode by UUID
  5. get_node_edges - Get all edges connected to a specific node
  6. get_episode_mentions - Get nodes and edges mentioned in an episode

Installation

Prerequisites

  • Go 1.21 or later
  • A Zep Cloud account with API key (sign up)

From Source

# Clone the repository
git clone https://github.com/getzep/zep.git
cd zep/mcp/zep-mcp-server

# Build the server
go build -o zep-mcp-server cmd/server/main.go

# Or install directly
go install github.com/getzep/zep/mcp/zep-mcp-server/cmd/server@latest

Configuration

Environment Variables

The server requires a Zep Cloud API key. You can provide it via environment variable or .env file.

Required:

  • ZEP_API_KEY - Your Zep Cloud API key

Optional:

  • LOG_LEVEL - Logging level: debug, info, warn, error (default: info)

Using .env File

  1. Copy the example configuration:

    cp .env.example .env

  2. Edit .env and add your API key:

    ZEP_API_KEY=your-zep-api-key-here
LOG_LEVEL=info

  3. Run the server:

    ./zep-mcp-server

Using Environment Variables

export ZEP_API_KEY=your-zep-api-key-here
./zep-mcp-server

Usage

Running the Server

The server supports two transport modes:

HTTP Mode (default):

./zep-mcp-server
# Or specify a custom port
./zep-mcp-server --port 9000

Stdio Mode (for Claude Desktop, Cline):

./zep-mcp-server --stdio

Docker

See Docker Deployment Guide for full Docker documentation.

Quick Start:

# Build the image
make docker-build

# Run with docker-compose
make docker-run

Or manually:

docker build -t zep-mcp-server:latest .
docker run -e ZEP_API_KEY=your-key -p 8080:8080 zep-mcp-server:latest

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "zep": {
      "command": "/path/to/zep-mcp-server",
      "args": ["--stdio"],
      "env": {
        "ZEP_API_KEY": "your-zep-api-key-here"
      }
    }
  }
}

Cline (VS Code Extension)

Add to your Cline MCP settings (.cline_mcp_settings.json):

{
  "mcpServers": {
    "zep": {
      "command": "/path/to/zep-mcp-server",
      "args": ["--stdio"],
      "env": {
        "ZEP_API_KEY": "your-zep-api-key-here"
      }
    }
  }
}

Claude Code (HTTP)

Claude Code uses HTTP transport to connect to MCP servers. Configure it using the claude mcp add CLI command.

  1. Start the server in HTTP mode (default):

    export ZEP_API_KEY=your-zep-api-key-here
./zep-mcp-server
# Server starts on http://localhost:8080

  2. Add the server to Claude Code:

    claude mcp add --transport http zep http://localhost:8080

  3. Verify the server is available:

    claude mcp list

Using Docker:

# Edit .env file with your ZEP_API_KEY
docker-compose up -d

# Add to Claude Code
claude mcp add --transport http zep http://localhost:8080

The HTTP transport supports both stateless JSON requests and streaming responses, allowing Claude Code and other HTTP-based MCP clients to interact with the Zep knowledge graph.

Tool Usage Examples

Search the Knowledge Graph

// Search for facts about a user
tools.search_graph({
  user_id: "user_123",
  query: "What are their preferences?",
  scope: "edges",  // edges, nodes, or episodes
  limit: 10
})

Get Thread Context

// Retrieve context for a conversation
tools.get_user_context({
  thread_id: "thread_456",
  template_id: "my_template"  // optional custom template
})

List User Threads

// Get all threads for a user
tools.list_threads({
  user_id: "user_123"
})

Query Graph Nodes

// Get entity nodes from the graph
tools.get_user_nodes({
  user_id: "user_123",
  limit: 10
})

Query Graph Edges

// Get relationship edges
tools.get_user_edges({
  user_id: "user_123",
  limit: 10
})

Get Episodes

// Get recent data ingestion events
tools.get_episodes({
  user_id: "user_123",
  lastn: 5
})

Development

Running Tests

# Run unit tests
go test ./...

# Run integration tests (requires ZEP_API_KEY)
export ZEP_API_KEY=your-key
go test ./test/integration/... -v

# Run all tests
go test -v ./...

Building

# Build for current platform
go build -o zep-mcp-server cmd/server/main.go

# Build for multiple platforms
GOOS=darwin GOARCH=arm64 go build -o zep-mcp-server-darwin-arm64 cmd/server/main.go
GOOS=darwin GOARCH=amd64 go build -o zep-mcp-server-darwin-amd64 cmd/server/main.go
GOOS=linux GOARCH=amd64 go build -o zep-mcp-server-linux-amd64 cmd/server/main.go
GOOS=windows GOARCH=amd64 go build -o zep-mcp-server-windows-amd64.exe cmd/server/main.go

Project Structure

mcp/zep-mcp-server/
├── cmd/server/           # Main entry point
├── internal/
│   ├── config/          # Configuration management
│   ├── handlers/        # Tool handlers
│   ├── server/          # MCP server setup
│   └── transform/       # Validation and formatting utilities
├── pkg/zep/             # Zep client wrapper
├── test/
│   ├── client/          # Test harness using Go MCP SDK
│   └── integration/     # Integration tests
└── docs/                # Additional documentation

Troubleshooting

Server won't start

Problem: ZEP_API_KEY environment variable is required

Solution: Set your API key in .env file or as an environment variable:

export ZEP_API_KEY=your-key

Connection errors

Problem: Tool calls fail with connection errors

Solution: Verify your API key is valid and check your network connectivity. Test with:

curl -H "Authorization: Bearer $ZEP_API_KEY" https://api.getzep.com/api/v2/users

User/Thread not found errors

Problem: 404 Not Found errors for users or threads

Solution: These are expected if the user or thread doesn't exist in your Zep Cloud instance. Create them first via the Zep SDK or API.

Slow performance

Problem: Tool calls take a long time

Solution:

  • Reduce limit parameters in search queries
  • Use search filters (node_labels, edge_types) to narrow results
  • Check your network latency to Zep Cloud

Documentation

License

Apache License 2.0 - see LICENSE for details.

Support

Contributing

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

Credits

Built with: