STARWARCLOUD STARWAR.AI
返回市场
MCP服务器-ZEP云

MCP服务器-ZEP云

作者：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 密钥

安装

  1. 克隆此仓库：
git clone https://github.com/yourusername/mcp-server-zep-cloud.git
cd mcp-server-z
  1. 创建并激活虚拟环境：
# 在 macOS/Linux 上
python -m venv venv
source venv/bin/activate

# 在 Windows 上
python -m venv venv
venv\Scripts\activate
  1. 安装所需的包：
pip install -r config/requirements.txt
  1. 复制 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

  1. 打开你的 Claude Desktop 配置文件：

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

  2. 使用绝对路径更新配置中的 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 将能够访问以下工具：

  1. 用户管理：
    • create_user: 创建新用户
    • get_user: 获取用户详情
    • update_user: 更新用户元数据
    • delete_user: 删除用户
  • list_users: 列出所有用户

  1. 集合管理：

    • create_collection: 创建新集合
    • get_collection: 获取集合详情
    • update_collection: 更新集合元数据
    • delete_collection: 删除集合
    • list_collections: 列出所有集合

  2. 记忆操作：

    • add_memory: 为用户向集合中添加记忆
    • get_memory: 从集合中获取用户记忆
    • list_memories: 列出用户集合中的记忆
    • search_memories: 搜索用户集合中的记忆

  3. 连接性：

    • 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 作为参考来创建自己的配置。

第一次设置以贡献代码

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

安全检查

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

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