mcp-server-zep-cloud

Vasiliy-Bondarenko/mcp-server-zep-cloud

3.1

If you are the rightful owner of mcp-server-zep-cloud and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

MCP Server for Zep Cloud provides a bridge between LLM clients and the Zep Cloud API, enabling memory management for AI assistants.

Tools
12
Resources
0
Prompts
0

MCP Server for Zep Cloud

smithery badge

MCP Server for Zep Cloud provides a bridge between LLM clients and the Zep Cloud API, enabling memory management for AI assistants.

Overview

An MCP server for storing and retrieving user memories, preferences, procedures, and factual relationships through the Zep Cloud API. It acts as a semantic memory layer that enables AI assistants to maintain context about users across conversations.

Tools

  1. User Management:

    • create_user: Create a new user with optional metadata, name, and email
    • get_user: Get user details by ID
    • update_user: Update a user's metadata
    • delete_user: Delete a user permanently
    • list_users: List users with pagination support

  2. Graph Operations:

    • search_graph: Search user's or group's memory graph (flexible user_id/group_id)
    • add_graph_data: Add data with optional timestamps and source info

  3. Group Management:

    • create_group: Create a new group for shared knowledge
    • get_group: Get group information by ID
    • update_group: Update group settings (currently limited by API)
    • delete_group: Delete a group permanently

  4. Connectivity:

    • check_connection: Verify API connectivity and configuration

Environment Variables

NameDescriptionDefault Value
ZEP_API_KEYAPI key for the Zep Cloud serviceNone
MCP_HOSTHost to bind the server to0.0.0.0
MCP_PORTPort to run the server on8080

Installation

Using Smithery

npx @smithery/cli install mcp-server-zep-cloud --client claude

Manual Installation with Claude Desktop

  1. Clone this repository:
git clone https://github.com/yourusername/mcp-server-zep-cloud.git
cd mcp-server-zep-cloud
  1. Install dependencies:
pip install -r config/requirements.txt
  1. Configure Claude Desktop by adding to claude_desktop_config.json:
{
  "mcpServers": {
    "zep-cloud": {
      "command": "python",
      "args": ["/path/to/mcp-server-zep-cloud/core/run_server.py"],
      "env": {
        "ZEP_API_KEY": "your_api_key_here"
      }
    }
  }
}

The configuration file is located at:

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

Using Docker

A Dockerfile is available for building and running the MCP server:

# Build the container
docker build -t mcp-server-zep-cloud .

# Run the container
docker run -p 8080:8080 \
  -e ZEP_API_KEY="your-api-key" \
  mcp-server-zep-cloud

Error Handling

The server uses a comprehensive error handling system to provide clear feedback:

Error Response Format

All tool responses follow a consistent format:

{
  "status": "ok|error",
  "error": "error description or empty string",
  "data": {...}  // only present when status is "ok"
}

Error Types

Unrecoverable Errors (require user action):

  • "API key not configured" - ZEP_API_KEY environment variable not set
  • "Invalid API key" - Authentication failed with Zep Cloud
  • "Access denied - check account status" - Account access issues

Recoverable Errors (temporary issues):

  • Network timeouts and connection errors
  • Rate limiting
  • Service temporary downtime

Connection Status

Use the check_connection tool to verify API connectivity:

Success Response:

{"status": "ok", "error": "", "connected": true, "message": "Connected to Zep Cloud API"}

Error Response:

{"status": "error", "error": "API key not configured", "connected": false}

Repository Structure

mcp-server-zep-cloud/
├── core/                          # Core MCP server implementation
│   ├── run_server.py             # Main MCP server entry point - this is just a wrapper, not real functionality in here
│   ├── zep_cloud_server.py       # Main ZepMCPServer class with 12 MCP tools
│   └── zep_cloud_client.py       # Zep SDK wrapper (legacy, not used)
│
├── tests/                         # Comprehensive test suite
│   └── test_mcp_e2e.py           # E2E tests for all 12 MCP tools (717 lines)
│
├── scripts/                       # Development and testing utilities
│   ├── run_server.sh             # Server startup with proxy config
│   ├── check_security.sh         # Security validation
│   └── test_*.py                 # Individual API testing scripts
│
├── config/                        # Configuration and dependencies
│   ├── requirements.txt          # Python dependencies
│   └── claude_desktop_config.json.example  # Claude Desktop config template
│
├── context/                       # Session and development context
│   └── *.md                      # Saved development sessions
│
├── venv/                         # Python virtual environment
├── run_tests.sh                  # Test runner with proxy configuration
├── smithery.yaml                 # Smithery package metadata
├── Dockerfile                    # Container deployment
└── .env                         # Environment variables (not in repo)

Key Files Explained

Core Implementation:

  • core/zep_cloud_server.py (293 lines) - Main MCP server with 12 tools:
    • User management: create_user, update_user, get_user, delete_user, list_users
    • Graph operations: add_graph_data, search_graph
    • Group management: create_group, get_group, update_group, delete_group
    • Connectivity: check_connection

Testing & Development:

  • tests/test_mcp_e2e.py (717 lines) - 31 E2E tests, 93.5% pass rate
  • run_tests.sh - Test runner with HTTP_PROXY=127.0.0.1:12334 for Cloudflare bypass
  • scripts/run_server.sh - Development server with environment isolation

Configuration:

  • .env - ZEP_API_KEY and proxy settings (create from template)
  • config/requirements.txt - zep-cloud, fastmcp, pytest dependencies

Security Considerations

  • API Key Protection: Never commit your API key to version control
  • Environment Variables: Use environment variables for sensitive data
  • Restricted Access: Limit the server to trusted networks

Support for Other Clients

This MCP server is designed to work with any MCP-compatible client. It has been tested with:

  • Claude Desktop
  • Claude in web browser

Development

Zep docs are located at https://help.getzep.com/, but lots of it is NOT CORRECT. Missing params, etc. For real params they recommend to investigate real API Client at https://github.com/getzep/zep-python/tree/main/src/zep_cloud. For example group methods are here: https://github.com/getzep/zep-python/blob/main/src/zep_cloud/group/client.py, etc.

Test Runner

Run tests only through this script - it includes necessary proxy configuration for Cloudflare bypass.

# Run all tests
./run_tests.sh test_mcp_e2e.py

# Run specific test
./run_tests.sh tests/test_mcp_e2e.py::TestMCPGraphData::test_add_graph_data_text

# Run with verbose output
./run_tests.sh test_mcp_e2e.py -v

Test Coverage

  • 31 E2E tests covering all 12 MCP tools
  • 93.5% pass rate (29/31 tests passing)
  • Known issues: 2 tests skipped due to Zep API bug with group.update()

Running in Development Mode

cd scripts
./run_server.sh

Project Status 📊

  • Production Ready: MCP server is fully functional and ready for use
  • Test Coverage: 29/31 tests passing (93.5% success rate)
  • Known Issues: 2 tests skipped due to Zep API bug with group.update() returning 502
  • Documentation: Complete MCP documentation for all 12 tools

Contributing 🤝

When adding new features:

  1. Write tests first (TDD approach)
  2. Implement minimal code to pass tests
  3. Add MCP-format documentation
  4. Ensure all tests pass

License

This project is licensed under the MIT License - see the file for details.