Dpdpdpdp0987/zep-poke-mcp

Zep Poke MCP Server

A production-ready Model Context Protocol (MCP) server for integrating Zep AI memory and conversation management into AI applications. Built for use with Poke and other MCP-compatible clients.

Features

✨ Complete Zep Integration

• 🔍 Semantic conversation search
• 💾 Context and message storage
• 📜 Conversation history retrieval
• 🧠 Automatic fact extraction
• 📊 Memory session management
• 🆕 Session creation and initialization

🚀 Production Ready

• TypeScript with full type safety
• Error handling and validation
• Vercel deployment support
• Environment variable configuration
• Clean, maintainable code structure

Quick Start

Prerequisites

• Node.js 18+
• A Zep API key (get one at getzep.com)
• npm, yarn, or pnpm

Installation

1. Clone the repository

git clone https://github.com/Dpdpdpdp0987/zep-poke-mcp.git
cd zep-poke-mcp

2. Install dependencies

npm install
# or
yarn install
# or
pnpm install

3. Configure environment variables

cp .env.example .env

Edit .env and add your Zep API key:

ZEP_API_KEY=your_zep_api_key_here
ZEP_API_URL=https://api.getzep.com

4. Build the project

npm run build

5. Run the server

npm start

MCP Tools

This server provides 6 powerful tools for Zep AI integration:

1. search_conversations

Search through conversations using semantic search.

Parameters:

• query (required): Search query text
• sessionId (optional): Limit search to specific session
• limit (optional): Max results (default: 10)

Example:

{
  "query": "What did we discuss about project deadlines?",
  "limit": 5
}

2. store_context

Store a conversation message in Zep.

Parameters:

• sessionId (required): Unique session identifier
• role (required): "user", "assistant", or "system"
• content (required): Message content
• metadata (optional): Additional metadata object

Example:

{
  "sessionId": "user-123-session",
  "role": "user",
  "content": "I need help with the dashboard feature",
  "metadata": { "priority": "high" }
}

3. retrieve_history

Get conversation history for a session.

Parameters:

• sessionId (required): Session to retrieve
• limit (optional): Max messages (default: 20)

Example:

{
  "sessionId": "user-123-session",
  "limit": 10
}

4. extract_facts

Extract facts automatically identified by Zep from conversations.

Parameters:

• sessionId (required): Session to extract facts from

Example:

{
  "sessionId": "user-123-session"
}

5. list_memories

List all session memories.

Parameters:

• limit (optional): Max sessions to return (default: 50)

Example:

{
  "limit": 25
}

6. create_memory

Create a new session memory.

Parameters:

• sessionId (required): Unique session identifier
• metadata (optional): Session metadata

Example:

{
  "sessionId": "new-user-456",
  "metadata": { "userId": "456", "name": "Alice" }
}

Configuration for Poke

Add this to your Poke MCP configuration:

{
  "mcpServers": {
    "zep": {
      "command": "node",
      "args": ["/path/to/zep-poke-mcp/dist/index.js"],
      "env": {
        "ZEP_API_KEY": "your_zep_api_key_here",
        "ZEP_API_URL": "https://api.getzep.com"
      }
    }
  }
}

Vercel Deployment

Option 1: Deploy with Vercel CLI

1. Install Vercel CLI

npm install -g vercel

2. Login to Vercel

vercel login

3. Deploy

vercel

4. Set environment variables in Vercel dashboard

• Go to your project settings
• Add ZEP_API_KEY secret
• Optionally add ZEP_API_URL

Option 2: Deploy via GitHub

1. Push this repository to GitHub
2. Import project in Vercel Dashboard
3. Configure environment variables
4. Deploy!

Development

Project Structure

zep-poke-mcp/
├── src/
│   ├── index.ts        # Main MCP server implementation
│   └── zepai.ts        # Zep API client wrapper
├── dist/               # Compiled JavaScript (generated)
├── package.json        # Dependencies and scripts
├── tsconfig.json       # TypeScript configuration
├── vercel.json         # Vercel deployment config
├── .env.example        # Environment variables template
├── .gitignore          # Git ignore rules
└── README.md           # This file

Development Commands

# Watch mode for development
npm run dev

# Build for production
npm run build

# Run the server
npm start

# Lint code
npm run lint

Architecture

This MCP server follows best practices:

1. TypeScript First: Full type safety and IntelliSense support
2. Modular Design: Separate concerns (MCP server, Zep client, types)
3. Error Handling: Comprehensive error handling and validation
4. Environment Config: Secure credential management
5. Production Ready: Optimized for deployment and scaling

Zep AI Integration

This server integrates with Zep AI's powerful features:

• Persistent Memory: Store and retrieve conversation context
• Semantic Search: Find relevant information across all conversations
• Fact Extraction: Automatically identify and store key facts
• Session Management: Organize conversations by session
• Metadata Support: Attach custom metadata to messages and sessions

Learn more at Zep Documentation

Troubleshooting

"ZEP_API_KEY environment variable is required"

• Make sure you've created a .env file with your API key
• Verify the API key is correct

"Failed to search/store/retrieve"

• Check your Zep API key is valid
• Verify your Zep API URL is correct
• Ensure you have network connectivity
• Check Zep service status

Build errors

• Delete node_modules and dist folders
• Run npm install again
• Run npm run build

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

• Issues: GitHub Issues
• Zep Documentation: docs.getzep.com
• MCP Documentation: modelcontextprotocol.io

Author

Daniela Mümken

Built with ❤️ using Model Context Protocol and Zep AI