mcp -zep-cloud

This MCP server acts as a bridge between Claude Desktop and the Zep Cloud API to provide memory management capabilities for AI assistants. It exposes a set of Claude Desktop tools that let you manage users, memory collections, and memories, while handling connectivity to Zep Cloud with a fallback mode in case the API is unavailable. Once the server is running, Claude Desktop can issue tool calls such as create_user, get_user, update_user, delete_user, list_users, create_collection, get_collection, update_collection, delete_collection, list_collections, add_memory, get_memory, list_memories, and search_memories, as well as check_connection to verify connectivity. If authentication or network issues occur, the server automatically enters a fallback mode and simulates responses so Claude Desktop remains functional.

To use the tools, configure Claude Desktop to point at the local server endpoint (default http://127.0.0.1:8000) and ensure the Zep Cloud API key is provided in the environment. The server will route requests to Zep Cloud when available, and fall back to simulated responses when not.

Prerequisites:

• Python 3.8+ installed on your system
• Access to the Zep Cloud API and a valid API key
• Git for cloning the repository

Step-by-step installation:

1. Clone the repository and navigate into it:

git clone https://github.com/yourusername/mcp-server-zep-cloud.git
cd mcp-server-zep-cloud

2. Create and activate a virtual environment:

# macOS / Linux
python -m venv venv
source venv/bin/activate

# Windows
python -m venv venv
venv\Scripts\activate

3. Install dependencies:

pip install -r config/requirements.txt

4. Create your environment file with the Zep Cloud API key:

cp config/.env.example .env

Edit the .env file to include your key (example variable shown):

ZEP_API_KEY=your_api_key_here

5. Run the server:

• Using the provided script (recommended):

cd scripts
./run_server.sh

• Or directly with Python (alternative):

cd core
python zep_cloud_server.py

6. Verify the server is running by visiting http://127.0.0.1:8000 or by using the check_connection tool from Claude Desktop.

Notes and tips:

• Ensure the Zep Cloud API key is kept secret and not committed to version control; store it in a .env file and reference it via environment variables.
• If the Zep Cloud API is temporarily unavailable, the server enters fallback mode automatically. In this mode, API operations are simulated and will return success without contacting Zep Cloud.
• Claude Desktop configuration requires absolute paths to the Python executable in your virtual environment and the server script, as shown in the claude_desktop_config.json example.
• If you encounter authentication or network issues, consult the AUTHENTICATION_NOTE.md file referenced in the repository for troubleshooting guidance.
• You can customize server behavior via environment variables if needed (e.g., ports, timeouts) depending on how zep_cloud_server.py is implemented in your setup.