MCP服务器-ZEP云

Name: MCP服务器-ZEP云
Author: kev-hu

作者：kev-hu10 星标更新：2025-08-20

安装使用来源：spider==github.com

项目介绍

Zep Cloud 的 MCP 服务器

Zep Cloud 的 MCP 服务器在 Claude Desktop 和 Zep Cloud API 之间提供了一个桥梁，实现了对 AI 助手的记忆管理。

仓库结构

该仓库已组织成以下目录：

core/: 核心功能文件
- zep_cloud_client.py: Zep Cloud API 的客户端实现
- zep_cloud_server.py: 提供工具给 Claude Desktop 的 MCP 服务器
- run_server.py: 单独运行服务器的脚本
scripts/: 操作实用脚本
- check_user_exists.py: 检查用户是否存在于 Zep Cloud 中的实用程序
- create_specific_user.py: 在 Zep Cloud 中创建特定用户的脚本
- run_server.sh / run_server.bat: 设置好环境后运行服务器的 shell 脚本
- 其他用于测试和调试的各种实用脚本
tests/: 按功能组织的测试脚本
- test_specific_user.py: 所有用户操作的综合测试
- test_zep_cloud_client.py: Zep Cloud 客户端的单元测试
- test_comprehensive.py: 所有特性的完整 API 测试
config/: 配置文件
- .env.example: 环境配置模板
- .env.new: 更新后的环境配置
- claude_desktop_config.json.example: Claude Desktop 配置模板
- requirements.txt: 包依赖项

特性

用户管理: 在 Zep Cloud 中创建、检索、更新和删除用户
集合管理: 创建和管理记忆集合
记忆操作: 添加、检索和搜索记忆
现代实现: 使用 FastMCP 方法实现更高效且易于维护的服务器
备用模式: 如果无法访问 Zep Cloud API，则自动运行在备用模式下

要求

Python 3.8+
Zep Cloud API 密钥

安装

克隆此仓库：

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

创建并激活虚拟环境：

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

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

安装所需的包：

pip install -r config/requirements.txt

复制 config/.env.example 文件到 .env 并添加你的 Zep Cloud API 密钥：

cp config/.env.example .env

编辑 .env 文件并添加你的 Zep Cloud API 密钥：

ZEP_API_KEY=your_api_key_here

使用方法

启动服务器

要在 macOS/Linux 上启动服务器：

cd scripts
./run_server.sh

或在 Windows 上：

cd scripts
run_server.bat

默认情况下，服务器将在 http://127.0.0.1:8000 上启动。

测试 API 连接

要测试用户是否存在于 Zep Cloud 中：

cd scripts
python check_user_exists.py [user_id]

要在 Zep Cloud 中创建特定用户：

cd scripts
python create_specific_user.py

备用模式

如果服务器无法连接到 Zep Cloud API（由于身份验证问题、网络问题或其他原因），它将自动进入备用模式。在这种模式下：

所有 API 操作都将被模拟，并返回成功
不会实际发送或接收数据到 Zep Cloud API
将记录警告消息以指示服务器正在备用模式下运行
服务器将继续运行，允许 Claude Desktop 集成正常工作

有关潜在的身份验证问题及其解决方法，请参阅 AUTHENTICATION_NOTE.md 文件。

配置 Claude Desktop

打开你的 Claude Desktop 配置文件：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
使用绝对路径更新配置中的 Python 可执行文件和服务器脚本路径：

{
  "mcpServers": {
    "zep-cloud": {
      "command": "/ABSOLUTE/PATH/TO/venv/bin/python",
      "args": [
        "/ABSOLUTE/PATH/TO/core/zep_cloud_server.py"
      ]
    }
  }
}

重要提示：

将 /ABSOLUTE/PATH/TO/ 替换为你虚拟环境中 Python 可执行文件的实际路径和服务器脚本。
使用绝对路径，而不是相对路径。
在 Windows 上，路径中使用双反斜杠（例如，C:\\Users\\YourUsername\\...）。

Claude Desktop 中可用的工具

一旦配置完成，Claude Desktop 将能够访问以下工具：

用户管理：
- 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: 列出用户集合中的记忆
- search_memories: 搜索用户集合中的记忆
连接性：
- check_connection: 检查与 Zep Cloud API 的连接状态

故障排除

有关故障排除的信息，请参阅 AUTHENTICATION_NOTE.md 文档，其中包含了关于 API 连接性和身份验证问题的详细信息。

安全注意事项

API 密钥保护

绝不要将你的 API 密钥提交到版本控制。.gitignore 文件已配置为防止提交 .env 文件。
使用提供的 .env.example 作为模板，并创建自己的 .env 文件，其中包含实际的 API 密钥。
定期轮换你的 API 密钥，特别是如果你怀疑它们可能已被泄露。

配置文件

个人配置文件如 claude_desktop_config.json 包含系统特定的路径，不应提交到版本控制。
使用提供的 claude_desktop_config.json.example 作为参考来创建自己的配置。

第一次设置以贡献代码

在添加任何代码或配置文件之前，始终确保 .gitignore 已经提交。
复制 .env.example 到 .env 并添加你的 API 密钥。
复制 claude_desktop_config.json.example 到 claude_desktop_config.json 并更新路径。
在提交之前验证敏感文件是否被忽略：
```
git status --ignored
```

安全检查

在提交代码之前，始终检查是否意外包含：

API 密钥或凭证
个人文件路径或用户名
可能包含敏感信息的日志文件
包含调试信息的临时文件