🔍 MCP Server - Vector Search

🔍 MCP 服务 - 向量搜索

这是一款基于 FastMCP 构建的极速 Model Context Protocol (MCP) 服务，无缝结合 Neo4j 图数据库的能力与基于嵌入向量的高级向量搜索。该服务支持在知识图谱中进行智能语义搜索，让你通过自然语言查询，以闪电般的速度发现上下文相关的信息。

🏗️ 架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │◄──►│   Vector Search  │◄──►│      Neo4j      │
│   (Claude AI)   │    │      Server      │    │     Database    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │    Embeddings    │
                       └──────────────────┘

🚀 快速开始

前置条件

• Python 3.8+
• uv
• Neo4j 数据库（v5.0+），并安装 APOC 插件
• OpenAI API 密钥

使用 uv 安装

1. 安装 uv（如果尚未安装）

   # On macOS and Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # On Windows
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   

2. 克隆并设置项目

   git clone https://github.com/omarguzmanm/mcp-server-vector-search.git
   cd mcp-server-vector-search
   
   # Create virtual environment and install dependencies
   uv venv
   uv pip install fastmcp neo4j openai python-dotenv sentence-transformers pydantic
   

3. 配置环境

   # Create .env file
   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
   

4. 启动服务

   # Activate virtual environment
   source .venv/bin/activate  # On Linux/macOS
   # or
   .venv\Scripts\activate     # On Windows
   
   # Start the FastMCP server in development mode
   mcp dev server.py
   

🛠️ 工具

该服务提供一个专为向量搜索优化的强大工具：

🔍 向量搜索

vector_search_neo4j(
    prompt="Find documents about machine learning and neural networks"
)

功能：

• 使用 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 要求

1. APOC 插件：高级图操作必不可少
2. 向量索引：必须支持 OpenAI 嵌入向量所需的 1536 维
3. 节点结构：节点应将 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"
      }
    }
  }
}

🐛 故障排除

常见问题

1. “找不到模块”错误

   # Reinstall dependencies with uv
   uv pip install --force-reinstall fastmcp neo4j openai
   

2. “找不到向量索引”

   // Check existing indexes
   SHOW INDEXES
   
   // Create if missing
   CREATE VECTOR INDEX descriptionIndex FOR (n:Label) ON (n.embedding)
   OPTIONS {indexConfig: {`vector.dimensions`: 1536, `vector.similarity_function`: 'cosine'}}
   

3. OpenAI API 错误

   # Verify API key
   uv run python -c "
   import os
   from openai import OpenAI
   client = OpenAI(api_key=os.getenv('OPENAI_API_KEY'))
   print('API key is valid!' if client.api_key else 'API key missing!')
   "
   

🤝 参与贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 安装开发依赖项：uv pip install -e ".[dev]"
4. 进行修改并添加测试
5. 提交：git commit -m 'Add amazing feature'
6. 推送：git push origin feature/amazing-feature
7. 创建 Pull Request

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

🙏 致谢

• FastMCP - 感谢提供出色的 MCP 框架
• uv - 感谢提供极速的 Python 包管理
• Neo4j - 感谢提供强大的图数据库功能
• OpenAI - 感谢提供先进的嵌入模型
• Model Context Protocol - 感谢提供协议规范

---