MCP服务器向量搜索

Name: MCP服务器向量搜索
Author: omarguzmanm

作者：omarguzmanm2 星标更新：2025-06-06

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

项目介绍

🔍 MCP 服务器 - 向量搜索

一个基于FastMCP构建的超快速模型上下文协议（MCP）服务器，它无缝结合了Neo4j的图数据库能力和通过嵌入实现的高级向量搜索。此服务器支持在知识图谱上进行智能语义搜索，允许您通过自然语言查询以闪电般的速度发现上下文相关的数据。

🏗️ 架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP 客户端    │◄──►│   向量搜索       │◄──►│      Neo4j      │
│   (Claude AI)   │    │      服务器      │    │     数据库      │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │    嵌入         │
                       └──────────────────┘

🚀 快速开始

先决条件

Python 3.8+
uv
Neo4j 数据库 (v5.0+) 并安装 APOC 插件
OpenAI API 密钥

使用 uv 安装

安装 uv（如果尚未安装）

# 在 macOS 和 Linux 上
curl -LsSf https://astral.sh/uv/install.sh | sh

# 在 Windows 上
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

克隆并设置项目

git clone https://github.com/omarguzmanm/mcp-server-vector-search.git
cd mcp-server-vector-search

# 创建虚拟环境并安装依赖项
uv venv
uv pip install fastmcp neo4j openai python-dotenv sentence-transformers pydantic

环境配置

# 创建 .env 文件
cp .env.example .env

编辑 .env 文件，添加您的配置：

NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_neo4j_password
NEO4J_DATABASE=neo4j
OPENAI_API_KEY=your_openai_api_key

Neo4j 向量索引设置

// 创建针对 1536 维度 OpenAI 嵌入的向量索引
// 如果不工作
CREATE VECTOR INDEX embeddableIndex FOR (n:Document) ON (n.embedding)
OPTIONS {indexConfig: {
  `vector.dimensions`: 1536,
  `vector.similarity_function`: 'cosine'
}}

启动服务器

# 激活虚拟环境
source .venv/bin/activate  # 在 Linux/macOS 上
# 或
.venv\Scripts\activate     # 在 Windows 上

# 启动 FastMCP 服务器
python main.py

🛠️ 工具

服务器提供了一个强大的工具，优化用于向量搜索：

🔍 向量搜索

vector_search_neo4j(
    prompt="查找关于机器学习和神经网络的文档"
)

功能：

将您的自然语言查询转换为 1536 维度的向量（使用 OpenAI）
在 Neo4j 向量索引中搜索最语义相似的节点
返回带有相似度评分的排名结果

⚙️ 配置

环境变量

变量	描述	是否必需	默认值
`NEO4J_URI`	Neo4j 连接 URI	✅	`bolt://localhost:7687`
`NEO4J_USERNAME`	Neo4j 用户名	✅	`neo4j`
`NEO4J_PASSWORD`	Neo4j 密码	✅	`password`
`NEO4J_DATABASE`	Neo4j 数据库名称	✅	`neo4j`
`OPENAI_API_KEY`	OpenAI API 密钥	❌	`all-MiniLM-L6-v2 模型`

Neo4j 要求

APOC 插件：用于高级图操作
向量索引：必须支持 1536 维度的 OpenAI 嵌入
节点结构：节点应具有作为向量的 embedding 属性

性能优化

uv 优势：与 pip 相比，依赖解析速度快 10-100 倍
FastMCP 优点：最小开销，优化用于 MCP 协议
连接池：自动管理 Neo4j 连接
异步操作：非阻塞 I/O，实现最大吞吐量

🤝 与 Claude Desktop 集成

MCP 配置

添加到您的 Claude Desktop MCP 设置中：

{
  "mcpServers": {
      "mcp-neo4j-vector-search": {
      "command": "python",
      "args": [
        "you\\server.py",
        "--with",
        "mcp[cli]",
        "--with",
        "neo4j",
        "--with",
        "pydantic"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your_password",
        "NEO4J_DATABASE": "neo4j",
        "OPENAI_API_KEY": "your_api_key"
      }
    }
  }
}

🐛 故障排除

常见问题

“模块未找到”错误

# 重新安装依赖项
uv pip install --force-reinstall fastmcp neo4j openai

“向量索引未找到”

// 检查现有索引
SHOW INDEXES

// 如有缺失，请创建
CREATE VECTOR INDEX embeddableIndex FOR (n:Document) ON (n.embedding)
OPTIONS {indexConfig: {`vector.dimensions`: 1536, `vector.similarity_function`: 'cosine'}}

OpenAI API 错误

# 验证 API 密钥
uv run python -c "
import os
from openai import OpenAI
client = OpenAI(api_key=os.getenv('OPENAI_API_KEY'))
print('API 密钥有效！' if client.api_key else '缺少 API 密钥！')
"

🤝 贡献

分叉仓库
创建功能分支：git checkout -b feature/amazing-feature
安装开发依赖项：uv pip install -e ".[dev]"
修改代码并添加测试
提交：git commit -m '添加精彩功能'
推送：git push origin feature/amazing-feature
打开拉取请求

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件获取详情。

🙏 致谢

FastMCP - 提供了出色的 MCP 框架
uv - 提供了超快的 Python 包管理
Neo4j - 提供了强大的图数据库能力
OpenAI - 提供了最先进的嵌入模型
模型上下文协议 - 提供了协议规范

<div align="center"> <p>🚀 为 AI 和图数据库社区制作 ❤️</p> <p> <a href="#-mcp-server---vector-search">⬆️ 回到顶部</a> </p> </div>