向量搜索服务器

Name: 向量搜索服务器
Author: miosomos

作者：miosomos3 星标更新：2025-09-04

安装使用来源：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

启动服务器

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

# 以开发模式启动FastMCP服务器
mcp dev server.py

🛠️ 工具

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

🔍 向量搜索

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

功能：

使用OpenAI将您的自然语言查询转换为1536维向量
在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密钥	✅	`text-embedding-small`

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重新安装依赖
uv pip install --force-reinstall fastm

“向量索引未找到”

// 检查现有索引
SHOW INDEXES

// 如果缺失则创建
CREATE VECTOR INDEX descriptionIndex FOR (n:Label) 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>