Graphiti MCP Server 🧠

Graphiti MCP Server 🧠

🌟 一个功能强大的知识图谱服务，使用 Neo4j 构建，并集成了模型上下文协议（MCP），专为 AI Agent 打造。

🚀 功能

• 🔄 使用 Neo4j 动态管理知识图谱
• 🤖 与 OpenAI 模型无缝集成
• 🔌 支持 MCP（模型上下文协议）
• 🐳 可通过 Docker 部署
• 🎯 支持自定义实体提取
• 🔍 提供高级语义搜索功能

🛠️ 安装

前置条件

• Docker 和 Docker Compose
• Python 3.10 或更高版本
• OpenAI API 密钥
• 至少 4GB RAM（建议 8GB）
• 2GB 可用磁盘空间

快速开始 🚀

1. 克隆代码库：

git clone https://github.com/gifflet/graphiti-mcp-server.git
cd graphiti-mcp-server

2. 设置环境变量：

cp .env.sample .env

3. 使用你的配置编辑 .env：

# Required for LLM operations
OPENAI_API_KEY=your_openai_api_key_here
MODEL_NAME=gpt-4.1-mini

# Optional: Custom OpenAI endpoint (e.g., for proxies)
# OPENAI_BASE_URL=https://api.openai.com/v1

# Neo4j Configuration (defaults work with Docker)
NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=demodemo

4. 启动服务：

docker compose up -d

5. 验证安装：

# Check if services are running
docker compose ps

# Check logs
docker compose logs graphiti-mcp

替代方案：环境变量

你也可以直接通过环境变量运行：

OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up

🔧 配置

服务端口 🌐

服务	端口	用途
Neo4j Browser	7474	用于图可视化的 Web 界面
Neo4j Bolt	7687	数据库连接
Graphiti MCP	8000	MCP 服务端点

环境变量 🔧

OpenAI 配置

变量	必填	默认值	说明
OPENAI_API_KEY	✅	-	你的 OpenAI API 密钥
OPENAI_BASE_URL	❌	-	自定义 OpenAI API 端点（由 OpenAI SDK 使用）
MODEL_NAME	❌	gpt-4.1-mini	要使用的主要大模型
SMALL_MODEL_NAME	❌	gpt-4.1-nano	用于轻量任务的小型大模型
LLM_TEMPERATURE	❌	0.0	大模型温度（0.0-2.0）
EMBEDDER_MODEL_NAME	❌	text-embedding-3-small	嵌入模型

Neo4j 配置

变量	必填	默认值	说明
NEO4J_URI	❌	bolt://neo4j:7687	Neo4j 连接 URI
NEO4J_USER	❌	neo4j	Neo4j 用户名
NEO4J_PASSWORD	❌	demodemo	Neo4j 密码

服务配置

变量	必填	默认值	说明
MCP_SERVER_HOST	❌	-	MCP 服务主机绑定地址
SEMAPHORE_LIMIT	❌	10	大模型调用的并发操作上限

Azure OpenAI 配置（可选）

对于 Azure OpenAI 部署，请使用以下环境变量，而不是标准 OpenAI 配置：

变量	必填	默认值	说明
AZURE_OPENAI_ENDPOINT	✅*	-	Azure OpenAI 端点 URL
AZURE_OPENAI_API_VERSION	✅*	-	Azure OpenAI API 版本
AZURE_OPENAI_DEPLOYMENT_NAME	✅*	-	Azure OpenAI 部署名称
AZURE_OPENAI_USE_MANAGED_IDENTITY	❌	false	使用 Azure 托管身份进行身份验证
AZURE_OPENAI_EMBEDDING_ENDPOINT	❌	-	用于嵌入的独立端点
AZURE_OPENAI_EMBEDDING_API_VERSION	❌	-	嵌入所用的 API 版本
AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME	❌	-	嵌入所用的部署名称
AZURE_OPENAI_EMBEDDING_API_KEY	❌	-	嵌入所用的独立 API 密钥

* 使用 Azure OpenAI 时必填

注意：

• OPENAI_BASE_URL 由 OpenAI Python SDK 直接使用，适用于代理配置或自定义端点
• SEMAPHORE_LIMIT 控制大模型 API 调用的并发数；遇到速率限制时请调低，需要更高吞吐量时请调高
• Azure 配置是标准 OpenAI 配置的替代方案，请勿混用两种配置

Neo4j 设置 🗄️

Neo4j 的默认配置：

• 用户名：neo4j
• 密码：demodemo
• URI：bolt://neo4j:7687（在 Docker 网络内）
• 针对开发进行了优化的内存设置

Docker 环境变量 🐳

你可以直接通过环境变量运行：

OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up

对于 Azure OpenAI：

AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com \
AZURE_OPENAI_API_VERSION=2024-02-01 \
AZURE_OPENAI_DEPLOYMENT_NAME=your-deployment \
OPENAI_API_KEY=your_key \
docker compose up

🔌 集成

Cursor IDE 集成 🖥️

1. 配置 Cursor MCP 设置：

{
  "mcpServers": {
    "Graphiti": {
      "command": "uv",
      "args": ["run", "graphiti_mcp_server.py"],
      "env": {
        "OPENAI_API_KEY": "your_key_here"
      }
    }
  }
}

2. 使用基于 Docker 的设置：

{
  "mcpServers": {
    "Graphiti": {
      "url": "http://localhost:8000/sse"
    }
  }
}

3. 将 Graphiti 规则添加到 Cursor 的用户规则中（参见 graphiti_cursor_rules.mdc）
4. 在 Cursor 中启动 Agent 会话

其他 MCP 客户端

此服务支持标准 MCP 传输方式：

• SSE（服务器发送事件）： http://localhost:8000/sse
• WebSocket： ws://localhost:8000/ws
• Stdio： 直接进程通信

💻 开发

本地开发设置

1. 安装依赖项：

# Using uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# Or using pip
pip install -r requirements.txt

2. 在本地启动 Neo4j：

docker run -d \
  --name neo4j-dev \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/demodemo \
  neo4j:5.26.0

3. 运行服务：

# Set environment variables
export OPENAI_API_KEY=your_key
export NEO4J_URI=bolt://localhost:7687

# Run with stdio transport
uv run graphiti_mcp_server.py

# Or with SSE transport
uv run graphiti_mcp_server.py --transport sse --use-custom-entities

测试

# Run basic connectivity test
curl http://localhost:8000/health

# Test MCP endpoint
curl http://localhost:8000/sse

🔍 故障排除

常见问题

🐳 Docker 问题

# Clean up and restart
docker compose down -v
docker compose up --build

# Check disk space
docker system df

日志和调试

# View all logs
docker compose logs -f

# View specific service logs
docker compose logs -f graphiti-mcp
docker compose logs -f neo4j

# Enable debug logging
docker compose up -e LOG_LEVEL=DEBUG

性能问题

• 内存： 在 docker-compose.yml 中增大 Neo4j 堆大小
• 存储： 监控 Neo4j 数据卷的使用情况
• 网络： 检查防火墙是否阻止了端口 7474、7687、8000

🏗️ 架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │    │  Graphiti MCP    │    │     Neo4j       │
│   (Cursor)      │◄──►│     Server       │◄──►│   Database      │
│                 │    │   (Port 8000)    │    │  (Port 7687)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │   OpenAI API     │
                       │   (LLM Client)   │
                       └──────────────────┘

组件

• Neo4j 数据库： 图存储和查询
• Graphiti MCP 服务： API 层和大模型操作
• OpenAI 集成： 实体提取和语义处理
• MCP 协议： 标准化的 AI Agent 通信

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

📝 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

🙏 致谢

• 感谢 Neo4j 团队提供出色的图数据库
• 感谢 OpenAI 提供强大的大模型
• 感谢 MCP 社区 制定协议规范
• 感谢 Graphiti Core 提供知识图谱框架

---

需要帮助？ 请提交 issue，或查看上面的故障排除指南。