mcp-neo4j-memory

🧠🕸️ Neo4j 知识图谱记忆 MCP 服务

mcp-name: io.github.neo4j-contrib/mcp-neo4j-memory

🌟 概述

一种 Model Context Protocol（MCP）服务实现，通过集成 Neo4j 图数据库提供持久化记忆能力。

通过以图结构存储信息，此服务可以将实体之间的复杂关系保存为记忆节点，并支持长期保留知识，以便在多个对话或会话中查询和分析。

借助 Neo4j Aura，你可以免费托管自己的数据库服务，也可以与协作者共享。或者，你也可以在本地运行自己的 Neo4j 服务。

此 MCP 服务利用 Neo4j 图数据库的能力，创建互联的知识库，作为外部记忆系统。通过 Cypher 查询，它可以探索和检索存储的信息、分析不同数据点之间的关系，并根据积累的知识生成见解。还可以借助 Claude 的能力进一步增强此记忆。

🕸️ 图架构

• Memory - 表示实体的节点，包含名称、类型和观察信息。
• Relationship - 表示两个实体之间的关系，并包含关系类型。

🔍 使用示例

Let's add some memories 
I, Michael, living in Dresden, Germany work at Neo4j which is headquartered in Sweden with my colleagues Andreas (Cambridge, UK) and Oskar (Gothenburg, Sweden)
I work in Product Management, Oskar in Engineering and Andreas in Developer Relations.

这会使 Claude 调用 create_entities 和 create_relations 工具。

📦 组件

🔧 工具

此服务提供以下核心工具：

🔎 查询工具

• read_graph

  • 读取整个知识图谱
  • 无需输入
  • 返回：包含实体和关系的完整图谱

• search_nodes

  • 根据查询搜索节点
  • 输入：
    • query（字符串）：用于匹配名称、类型和观察信息的搜索查询
  • 返回：匹配的子图

• find_nodes

  • 按名称查找特定节点
  • 输入：
    • names（字符串数组）：要检索的实体名称
  • 返回：包含指定节点的子图

♟️ 实体管理工具

• create_entities

  • 在知识图谱中创建多个新实体
  • 输入：
    • entities：对象数组，包含：
      • name（字符串）：实体名称
      • type（字符串）：实体类型
      • observations（字符串数组）：关于实体的初始观察信息
  • 返回：已创建的实体

• delete_entities

  • 删除多个实体及其相关关系
  • 输入：
    • entityNames（字符串数组）：要删除的实体名称
  • 返回：成功确认

🔗 关系管理工具

• create_relations

  • 在实体之间创建多个新关系
  • 输入：
    • relations：对象数组，包含：
      • source（字符串）：源实体名称
      • target（字符串）：目标实体名称
      • relationType（字符串）：关系类型
  • 返回：已创建的关系

• delete_relations

  • 从图谱中删除多个关系
  • 输入：
    • relations：对象数组，架构与 create_relations 相同
  • 返回：成功确认

📝 观察信息管理工具

• add_observations

  • 向现有实体添加新的观察信息
  • 输入：
    • observations：对象数组，包含：
      • entityName（字符串）：要添加观察信息的实体
      • contents（字符串数组）：要添加的观察信息
  • 返回：已添加观察信息的详细信息

• delete_observations

  • 从实体中删除指定的观察信息
  • 输入：
    • deletions：对象数组，包含：
      • entityName（字符串）：要从中删除观察信息的实体
      • observations（字符串数组）：要删除的观察信息
  • 返回：成功确认

🔧 在 Claude Desktop 中使用

💾 安装

pip install mcp-neo4j-memory

⚙️ 配置

使用以下配置将服务添加到你的 claude_desktop_config.json：

"mcpServers": {
  "neo4j": {
    "command": "uvx",
    "args": [
      "[email protected]",
      "--db-url",
      "neo4j+s://xxxx.databases.neo4j.io",
      "--username",
      "<your-username>",
      "--password",
      "<your-password>"
    ]
  }
}

或者，你也可以设置环境变量：

"mcpServers": {
  "neo4j": {
    "command": "uvx",
    "args": [ "[email protected]" ],
    "env": {
      "NEO4J_URL": "neo4j+s://xxxx.databases.neo4j.io",
      "NEO4J_USERNAME": "<your-username>",
      "NEO4J_PASSWORD": "<your-password>"
    }
  }
}

命名空间

对于多租户部署，请添加 --namespace 为工具名称添加前缀：

"args": [ "[email protected]", "--namespace", "myapp", "--db-url", "..." ]

工具名称会变为：myapp-read_graph、myapp-create_entities 等。

也可以使用 NEO4J_NAMESPACE 环境变量。

🌐 HTTP 传输模式

该服务支持 HTTP 传输，适用于基于 Web 的部署和微服务：

# Basic HTTP mode (defaults: host=127.0.0.1, port=8000, path=/mcp/)
mcp-neo4j-memory --transport http

# Custom HTTP configuration
mcp-neo4j-memory --transport http --host 127.0.0.1 --port 8080 --path /mcp/

HTTP 配置的环境变量：

export NEO4J_TRANSPORT=http
export NEO4J_MCP_SERVER_HOST=127.0.0.1
export NEO4J_MCP_SERVER_PORT=8080
export NEO4J_MCP_SERVER_PATH=/mcp/
export NEO4J_NAMESPACE=myapp
mcp-neo4j-memory

🔄 传输模式

该服务支持三种传输模式：

• STDIO（默认）：用于本地工具和 Claude Desktop 的标准输入/输出
• SSE：用于基于 Web 的部署的服务器发送事件
• HTTP：适用于现代 Web 部署和微服务的可流式 HTTP

🐳 使用 Docker

"mcpServers": {
  "neo4j": {
    "command": "docker",
    "args": [
      "run",
      "--rm",
      "-e", "NEO4J_URL=neo4j+s://xxxx.databases.neo4j.io",
      "-e", "NEO4J_USERNAME=<your-username>",
      "-e", "NEO4J_PASSWORD=<your-password>",
      "mcp/neo4j-memory:0.4.5"
    ]
  }
}

🔒 安全防护

该服务提供全面的安全防护，并采用安全默认设置，可防御常见的基于 Web 的攻击，同时在使用 HTTP 传输时保留完整的 MCP 功能。

🛡️ DNS 重绑定防护

TrustedHost Middleware 会验证 Host 标头，以防止 DNS 重绑定攻击：

默认安全设置：

• 默认仅允许 localhost 和 127.0.0.1 主机

环境变量：

export NEO4J_MCP_SERVER_ALLOWED_HOSTS="example.com,www.example.com"

🌐 CORS 防护

**跨源资源共享（CORS）**防护默认会阻止基于浏览器的请求：

环境变量：

export NEO4J_MCP_SERVER_ALLOW_ORIGINS="https://example.com,https://app.example.com"

🔧 完整的安全配置

开发环境设置：

mcp-neo4j-memory --transport http \
  --allowed-hosts "localhost,127.0.0.1" \
  --allow-origins "http://localhost:3000"

生产环境设置：

mcp-neo4j-memory --transport http \
  --allowed-hosts "example.com,www.example.com" \
  --allow-origins "https://example.com,https://app.example.com"

🚨 安全最佳实践

对于 allow_origins：

• 明确指定：["https://example.com", "https://example.com"]
• 在生产环境中使用凭据时，切勿使用 "*"
• 在生产环境中使用 HTTPS 源

对于 allowed_hosts：

• 添加实际域名：["example.com", "www.example.com"]
• 仅在开发环境中添加 localhost
• 除非了解相关风险，否则切勿使用 "*"

🐳 Docker 部署

Neo4j Memory MCP 服务可通过 Docker 部署，以供远程使用。Docker 部署应使用 HTTP 传输，以便通过 Web 访问。若要将此部署与 Claude Desktop 等应用程序集成，必须在 MCP 配置中使用代理，例如 mcp-remote。

📦 使用构建好的镜像

使用 docker build -t mcp-neo4j-memory:latest . 在本地构建后：

# Run with http transport (default for Docker)
docker run --rm -p 8000:8000 \
  -e NEO4J_URI="bolt://host.docker.internal:7687" \
  -e NEO4J_USERNAME="neo4j" \
  -e NEO4J_PASSWORD="password" \
  -e NEO4J_DATABASE="neo4j" \
  -e NEO4J_TRANSPORT="http" \
  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
  -e NEO4J_MCP_SERVER_PORT="8000" \
  -e NEO4J_MCP_SERVER_PATH="/mcp/" \
  mcp/neo4j-memory:latest

# Run with security middleware for production
docker run --rm -p 8000:8000 \
  -e NEO4J_URI="bolt://host.docker.internal:7687" \
  -e NEO4J_USERNAME="neo4j" \
  -e NEO4J_PASSWORD="password" \
  -e NEO4J_DATABASE="neo4j" \
  -e NEO4J_TRANSPORT="http" \
  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
  -e NEO4J_MCP_SERVER_PORT="8000" \
  -e NEO4J_MCP_SERVER_PATH="/mcp/" \
  -e NEO4J_MCP_SERVER_ALLOWED_HOSTS="example.com,www.example.com" \
  -e NEO4J_MCP_SERVER_ALLOW_ORIGINS="https://example.com" \
  mcp/neo4j-memory:latest

🔧 环境变量

变量	默认值	描述
NEO4J_URI	bolt://localhost:7687	Neo4j 连接 URI
NEO4J_USERNAME	neo4j	Neo4j 用户名
NEO4J_PASSWORD	password	Neo4j 密码
NEO4J_DATABASE	neo4j	Neo4j 数据库名称
NEO4J_TRANSPORT	stdio（本地），http（远程）	传输协议（stdio、http 或 sse）
NEO4J_MCP_SERVER_HOST	127.0.0.1（本地）	绑定的主机
NEO4J_MCP_SERVER_PORT	8000	HTTP/SSE 传输的端口
NEO4J_MCP_SERVER_PATH	/mcp/	用于访问 MCP 服务的路径
NEO4J_MCP_SERVER_ALLOW_ORIGINS	（为空 — 默认安全）	允许的 CORS 来源列表，以逗号分隔
NEO4J_MCP_SERVER_ALLOWED_HOSTS	localhost,127.0.0.1	允许的主机列表，以逗号分隔（防止 DNS 重绑定）
NEO4J_NAMESPACE	（为空 — 无前缀）	工具名称的命名空间前缀（例如，myapp-read_graph）

🌐 用于旧版 Web 访问的 SSE 传输

使用 SSE 传输（供旧版 Web 客户端使用）时，服务会公开一个 HTTP 端点：

# Start the server with SSE transport
docker run -d -p 8000:8000 \
  -e NEO4J_URI="neo4j+s://demo.neo4jlabs.com" \
  -e NEO4J_USERNAME="recommendations" \
  -e NEO4J_PASSWORD="recommendations" \
  -e NEO4J_DATABASE="neo4j" \
  -e NEO4J_TRANSPORT="sse" \
  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
  -e NEO4J_MCP_SERVER_PORT="8000" \
  --name neo4j-memory-mcp-server \
  mcp-neo4j-memory:latest

# Test the SSE endpoint
curl http://localhost:8000/sse

# Use with MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:8000/sse

🚀 开发

📦 先决条件

1. 安装 uv（通用虚拟环境工具）：

# Using pip
pip install uv

# Using Homebrew on macOS
brew install uv

# Using cargo (Rust package manager)
cargo install uv

2. 克隆仓库并设置开发环境：

# Clone the repository
git clone https://github.com/yourusername/mcp-neo4j-memory.git
cd mcp-neo4j-memory

# Create and activate virtual environment using uv
uv venv
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows

# Install dependencies including dev dependencies
uv pip install -e ".[dev]"

🐳 Docker

构建并运行 Docker 容器：

# Build the image
docker build -t mcp/neo4j-memory:latest .

# Run the container
docker run -e NEO4J_URL="neo4j+s://xxxx.databases.neo4j.io" \
          -e NEO4J_USERNAME="your-username" \
          -e NEO4J_PASSWORD="your-password" \
          mcp/neo4j-memory:latest

📄 许可证

此 MCP 服务采用 MIT 许可证。这意味着您可以自由使用、修改和分发此软件，但须遵守 MIT 许可证的条款和条件。详情请参阅项目仓库中的 LICENSE 文件。