图形编辑MCP服务器

Name: 图形编辑MCP服务器
Author: gifflet

作者：gifflet128 星标更新：2025-08-01

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

项目介绍

Graphiti MCP Server 🧠

🌟 一个强大的知识图谱服务器，用于AI代理，基于Neo4j构建，并与模型上下文协议（MCP）集成。

🚀 功能

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

🛠️ 安装

先决条件

Docker 和 Docker Compose
Python 3.10 或更高版本
OpenAI API密钥
最小4GB内存（建议8GB）
2GB空闲磁盘空间

快速开始 🚀

克隆仓库：

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

设置环境变量：

cp .env.sample .env

编辑.env以进行配置：

# LLM操作所需
OPENAI_API_KEY=your_openai_api_key_here
MODEL_NAME=gpt-4.1-mini

# 可选：自定义OpenAI端点（例如，用于代理）
# OPENAI_BASE_URL=https://api.openai.com/v1

# Neo4j配置（默认值适用于Docker）
NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=demodemo

启动服务：

docker compose up -d

验证安装：

# 检查服务是否运行
docker compose ps

# 查看日志
docker compose logs graphiti-mcp

替代方案：环境变量

你可以直接使用环境变量运行：

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

🔧 配置

服务端口 🌐

服务	端口	目的
Neo4j浏览器	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`	主LLM模型
`SMALL_MODEL_NAME`	❌	`gpt-4.1-nano`	轻任务的小型LLM模型
`LLM_TEMPERATURE`	❌	`0.0`	LLM温度（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`	LLM调用并发操作限制

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 控制并发LLM 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集成 🖥️

配置Cursor MCP设置：

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

对于基于Docker的设置：

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

向Cursor的用户规则添加Graphiti规则（参见graphiti_cursor_rules.mdc）
在Cursor中启动代理会话

其他MCP客户端

该服务器支持标准MCP传输：

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

💻 开发

本地开发设置

安装依赖项：

# 使用uv（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# 或使用pip
pip install -r requirements.txt

本地启动Neo4j：

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

运行服务器：

# 设置环境变量
export OPENAI_API_KEY=your_key
export NEO4J_URI=bolt://localhost:7687

# 使用stdio传输运行
uv run graphiti_mcp_server.py

# 或使用SSE传输
uv run graphiti_mcp_server.py --transport sse --use-custom-entities

测试

# 运行基本连通性测试
curl http://localhost:8000/health

# 测试MCP端点
curl http://localhost:8000/sse

🔍 故障排除

常见问题

🐳 Docker问题

# 清理并重新启动
docker compose down -v
docker compose up --build

# 检查磁盘空间
docker system df

日志和调试

# 查看所有日志
docker compose logs -f

# 查看特定服务的日志
docker compose logs -f graphiti-mcp
docker compose logs -f neo4j

# 启用调试日志
docker compose up -e LOG_LEVEL=DEBUG

性能问题

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

🏗️ 架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP客户端    │    │  Graphiti MCP    │    │     Neo4j       │
│   (Cursor)      │◄──►│     服务器       │◄──►│   数据库      │
│                 │    │   (端口8000)    │    │  (端口7687)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │   OpenAI API     │
                       │   (LLM客户端)   │
                       └──────────────────┘

组件

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

🤝 贡献

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

📝 许可证

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

🙏 致谢

Neo4j 团队提供的出色图形数据库
OpenAI 提供的强大LLM模型
MCP社区提供的协议规范
Graphiti核心提供的知识图框架

需要帮助？ 打开一个问题或查看上面的故障排除指南。