MCP Neo4j Ts

MCP Neo4j内存服务器（TypeScript）

一个高性能的模型上下文协议（MCP）服务器，使用Neo4j图形数据库提供持久内存存储。使用Bun运行时和TypeScript构建，具有增强的实体内容存储功能，可用于富文本、markdown、HTML和详细文档。

特性

• 11 MCP工具：完成实体、关系、观察和内容的CRUD操作
• 增强的内容存储：将富格文本（markdown、HTML、纯文本）与观察值一起存储
• 全文搜索：在实体名称、类型、观察结果和内容之间进行搜索
• HTTP传输：通过HTTP API进行基于Web的访问（无STDIO/SSE复杂性）
• 多实例就绪：同时运行多个特定于项目的实例
• Bun运行时：快速启动，原生TypeScript支持，无需构建步骤
• Docker Compose：使用Neo4j社区版轻松部署
• 类型安全：带Zod运行时验证的完整TypeScript
• 图数据库：利用Neo4j强大的图形功能

快速开始

先决条件

• 安装
• 对MCP和Neo4j的基本了解

单实例部署

1. 克隆并导航到项目：

   cd mcp-neo4j-ts

1. 创建环境文件：

   cp .env.example .env

1. 编辑 .env 并设置密码：

   NEO4J_PASSWORD=your_secure_password

1. 启动服务：

   docker-compose up -d

1. 验证部署：

   # Check server health
   curl http://localhost:8000/health

   # Access Neo4j browser
   open http://localhost:7474

您的MCP服务器现在正在运行 http://localhost:8000/mcp/!

多实例设置

使用隔离的数据库和不同的端口运行多个特定于项目的实例。

示例：运行三个项目

项目A（默认）：

# Create .env.project-a
cp .env.example .env.project-a

# Edit .env.project-a:
NEO4J_PASSWORD=projecta_password
NEO4J_BOLT_PORT=7687
MCP_SERVER_PORT=8000
NEO4J_DATA_DIR=./data/project-a

# Start
docker-compose --env-file .env.project-a up -d

项目B：

# Create .env.project-b
cp .env.example .env.project-b

# Edit .env.project-b:
NEO4J_PASSWORD=projectb_password
NEO4J_BOLT_PORT=7688
NEO4J_HTTP_PORT=7475
MCP_SERVER_PORT=8001
NEO4J_DATA_DIR=./data/project-b

# Start with project name
docker-compose --env-file .env.project-b -p project-b up -d

项目C：

# Create .env.project-c
cp .env.example .env.project-c

# Edit .env.project-c:
NEO4J_PASSWORD=projectc_password
NEO4J_BOLT_PORT=7689
NEO4J_HTTP_PORT=7476
MCP_SERVER_PORT=8002
NEO4J_DATA_DIR=./data/project-c

# Start with project name
docker-compose --env-file .env.project-c -p project-c up -d

现在你有三个独立的实例：

• 项目A： http://localhost:8000/mcp/
• 项目B： http://localhost:8001/mcp/
• 项目C： http://localhost:8002/mcp/

Claude桌面集成

添加到您的Claude Desktop配置(claude_desktop_config.json):

使用远程MCP网桥（推荐）：

{
  "mcpServers": {
    "neo4j-memory": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-remote",
        "http://localhost:8000/mcp/"
      ]
    }
  }
}

对于多个项目：

{
  "mcpServers": {
    "neo4j-memory-project-a": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-remote",
        "http://localhost:8000/mcp/"
      ]
    },
    "neo4j-memory-project-b": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-remote",
        "http://localhost:8001/mcp/"
      ]
    }
  }
}

注： 这 @modelcontextprotocol/server-remote 该包充当Claude Desktop和基于HTTP的MCP服务器之间的桥梁。

配置参考

所有配置都通过环境变量进行管理。看 .env.example 查看完整列表。

Neo4j配置

MCP服务器配置

api参考

MCP工具

服务器通过MCP协议公开11个工具：

1. read_graph

阅读整个知识图谱。

输入： 无

输出：

{
  "entities": [
    {
      "name": "John Doe",
      "type": "person",
      "observations": ["Software engineer", "Works at Company X"],
      "content": "# John Doe\n\n## Background\n..."
    }
  ],
  "relations": [
    {
      "source": "John Doe",
      "target": "Company X",
      "relationType": "WORKS_AT"
    }
  ]
}

2. search_memories

在所有实体字段（包括内容）中进行全文搜索。

输入：

{
  "query": "software engineer"
}

输出： KnowledgeGraph 具有匹配的实体和关系

3. find_memories_by_name

按确切名称查找实体。

输入：

{
  "names": ["John Doe", "Company X"]
}

输出： KnowledgeGraph 具有指定实体

4. create_entities

使用可选内容创建新实体。

输入：

{
  "entities": [
    {
      "name": "API Documentation",
      "type": "document",
      "observations": ["REST API", "Version 2.0"],
      "content": "# API Documentation\n\n## Endpoints\n- GET /users\n- POST /users"
    }
  ]
}

输出： 已创建实体

5. delete_entities

删除实体及其所有关系。

输入：

{
  "entityNames": ["Entity1", "Entity2"]
}

输出： 成功确认

6. create_relations

创建实体之间的关系。

输入：

{
  "relations": [
    {
      "source": "John Doe",
      "target": "Company X",
      "relationType": "WORKS_AT"
    }
  ]
}

输出： 建立关系

7. delete_relations

删除特定关系。

输入：

{
  "relations": [
    {
      "source": "John Doe",
      "target": "Company X",
      "relationType": "WORKS_AT"
    }
  ]
}

输出： 成功确认

8. add_observations

向实体添加观测值（自动消除重复）。

输入：

{
  "observations": [
    {
      "entityName": "John Doe",
      "observations": ["Knows Python", "Likes coffee"]
    }
  ]
}

输出： 新增观察结果的详细信息

9. delete_observations

从实体中删除具体观察结果。

输入：

{
  "deletions": [
    {
      "entityName": "John Doe",
      "observations": ["Old observation"]
    }
  ]
}

输出： 成功确认

10. update_content 新

更新或设置实体的富格文本内容。

输入：

{
  "updates": [
    {
      "entityName": "API Documentation",
      "content": "# Updated Documentation\n\nNew content here..."
    }
  ]
}

输出： 用新内容更新实体

使用案例：

• 存储降价文档
• 保存HTML代码段
• 做好详细记录
• 存档代码片段
• 存储格式化信息

11. delete_content 新

从实体中删除内容字段。

输入：

{
  "entityNames": ["Entity1", "Entity2"]
}

输出： 成功确认

内容存储指南

增强 content 字段允许在观察值旁边存储富格文本：

最佳实践

1. 使用markdown进行文档记录：

   {
     name: "User Guide",
     type: "document",
     content: "# User Guide\n\n## Getting Started\n..."
   }

1. 存储代码片段：

   {
     name: "Authentication Code",
     type: "code",
     content: "```python\ndef authenticate(user):\n    ...\n```"
   }

1. 做好详细记录：

   {
     name: "Meeting Notes",
     type: "note",
     content: "## Meeting with Client\n\nDate: 2024-01-15\n\nTopics:..."
   }

内容与观察

• 观察：简短、离散的事实（例如，“软件工程师”、“住在旧金山”）
• 内容：长篇、丰富的文本内容（例如，完整的文档、详细的注释）

两者都有全文搜索索引！

开发指南

本地开发（无Docker）

要求：

• 包子 安装
• Neo4j在本地运行

# Navigate to server directory
cd servers/mcp-neo4j-memory

# Install dependencies
bun install

# Set environment variables
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USERNAME=neo4j
export NEO4J_PASSWORD=password
export MCP_SERVER_PORT=8000

# Run the server
bun run src/index.ts

运行测试

cd servers/mcp-neo4j-memory
bun test

项目结构

mcp-neo4j-ts/
├── servers/
│   └── mcp-neo4j-memory/
│       ├── src/
│       │   ├── index.ts          # Entry point
│       │   ├── server.ts         # MCP server & tools
│       │   ├── neo4j-memory.ts   # Neo4j operations
│       │   ├── models.ts         # Zod schemas
│       │   └── config.ts         # Configuration
│       ├── tests/
│       ├── Dockerfile
│       └── package.json
├── docker-compose.yml
├── .env.example
└── README.md

故障排除

服务器无法启动

检查Docker服务：

docker-compose ps
docker-compose logs

验证Neo4j是否正常：

docker-compose logs neo4j

连接被拒绝

确保端口可用：

# Check if ports are in use
netstat -an | grep 8000
netstat -an | grep 7687

对于多实例，确保.env文件中的端口唯一

数据持久性问题

检查数据目录权限：

ls -la ./data/neo4j

验证卷装载：

docker-compose config

重置所有内容

# Stop and remove containers, networks, volumes
docker-compose down -v

# Remove data directories
rm -rf ./data ./logs

# Start fresh
docker-compose up -d

安全考虑

生产部署

1. 更改默认密码：

   NEO4J_PASSWORD=strong_random_password_here

1. 限制CORS：

   MCP_ALLOW_ORIGINS=https://yourdomain.com
   MCP_ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com

1. 使用HTTPS：

- 在反向代理（nginx、Caddy）后面部署 - 配置SSL证书

1. 网络隔离：

- 不要公开Neo4j端口 - 仅暴露MCP服务器端口

1. 定期备份：

   # Backup Neo4j data
   docker-compose exec neo4j neo4j-admin dump --database=neo4j --to=/backups/neo4j.dump

Python版本的增强功能

1. 内容字段：用实体存储富文本
2. 内容管理工具: update_content, delete_content
3. 增强型搜索：全文搜索包括内容
4. 更快的性能：Bun运行时间明显更快
5. 无构建步骤：直接执行TypeScript
6. 类型安全：带有Zod验证的完整TypeScript
7. 多实例设计：专为并行部署而设计
8. 较小的Docker镜像：Bun图像更紧凑
9. 现代堆栈：最新的TypeScript和HTTP框架

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交问题和拉取请求。

支持

对于问题和疑问：

• 检查 故障排除 章节
• 查看 配置参考
• 在GitHub上打开一个问题

致谢

• 基于Python mcp-neo4j存储器 实施