mcp-neo4j-内存

Name: mcp-neo4j-内存
Author: neo4j-contrib

作者：neo4j-contrib817 星标更新：2025-11-19

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

项目介绍

技术文档摘要

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

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

🌟 概述

这是一个通过集成 Neo4j 图数据库实现持久化内存能力的 Model Context Protocol (MCP) 服务器。

通过在图结构中存储信息，该服务器能够维护实体之间的复杂关系作为记忆节点，并支持长期保留知识，这些知识可以在多个对话或会话之间进行查询和分析。

使用 Neo4j Aura，您可以免费托管自己的数据库服务器，或者与您的合作者共享。否则，您也可以在本地运行自己的 Neo4j 服务器。

MCP 服务器利用 Neo4j 的图数据库功能创建一个相互连接的知识库，作为外部记忆系统。通过 Cypher 查询，它允许探索和检索存储的信息，分析不同数据点之间的关系，并从积累的知识中生成见解。这种记忆可以通过增强 Claude 的功能来进一步提升。

🕸️ 图模式

Memory - 表示具有名称、类型和观察结果的实体的节点。
Relationship - 两个实体之间的关系及其类型。

🔍 使用示例

让我们添加一些记忆
我，Michael，在德国德累斯顿工作，我的同事Andreas（英国剑桥）和Oskar（瑞典哥德堡）一起在总部位于瑞典的Neo4j公司工作。
我在产品管理部工作，Oskar在工程部门，Andreas在开发者关系部门。

结果是 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": [
      "mcp-neo4j-memory@0.4.2",
      "--db-url",
      "neo4j+s://xxxx.databases.neo4j.io",
      "--username",
      "<your-username>",
      "--password",
      "<your-password>"
    ]
  }
}

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

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

命名空间

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

"args": [ "mcp-neo4j-memory@0.4.2", "--namespace", "myapp", "--db-url", "..." ]

工具变为：myapp-read_graph，myapp-create_entities 等。

也可以使用 NEO4J_NAMESPACE 环境变量。

🌐 HTTP 传输模式

服务器支持 HTTP 传输以适应基于 Web 的部署和微服务：

# 基本 HTTP 模式（默认：host=127.0.0.1，port=8000，path=/mcp/）
mcp-neo4j-memory --transport http

# 自定义 HTTP 配置
mcp-neo4j-memory --transport http --host 127.0.0.1 --port 8080 --path /api/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=/api/mcp/
export NEO4J_NAMESPACE=myapp
mcp-neo4j-memory

🔄 传输模式

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

STDIO（默认）：标准输入/输出，适用于本地工具和 Claude Desktop
SSE：Server-Sent Events，适用于基于 Web 的部署
HTTP：流式 HTTP，适用于现代 Web 部署和微服务

🐳 使用 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.2"
    ]
  }
}

🔒 安全保护

服务器包括全面的安全保护措施，具有安全默认值，可以防止常见的基于 Web 的攻击，同时在使用 HTTP 传输时保留完整的 MCP 功能。

🛡️ DNS 重绑定保护

TrustedHost 中间件验证 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 记忆 MCP 服务器可以使用 Docker 进行远程部署。Docker 部署应使用 HTTP 传输以确保 Web 可访问性。为了将此部署与 Claude Desktop 等应用程序集成，您需要在 MCP 配置中使用代理，如 mcp-remote。

📦 使用构建的镜像

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

# 使用 http 传输运行（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

# 使用生产中间件运行
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`）

🌐 SSE 传输用于旧版 Web 访问

当使用 SSE 传输（针对旧版 Web 客户端）时，服务器暴露一个 HTTP 端点：

# 使用 SSE 传输启动服务器
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

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

# 使用 MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:8000/sse

🚀 开发

📦 先决条件

安装 uv（通用虚拟环境）：

# 使用 pip
pip install uv

# 使用 macOS 上的 Homebrew
brew install uv

# 使用 cargo（Rust 包管理器）
cargo install uv

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

# 克隆仓库
git clone https://github.com/yourusername/mcp-neo4j-memory.git
cd mcp-neo4j-memory

# 使用 uv 创建并激活虚拟环境
uv venv
source .venv/bin/activate  # 在 Unix/macOS 上
.venv\Scripts\activate     # 在 Windows 上

# 安装依赖项，包括开发依赖项
uv pip install -e ".[dev]"

🐳 Docker

构建并运行 Docker 容器：

# 构建镜像
docker build -t mcp/neo4j-memory:latest .

# 运行容器
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 文件。