🔍 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 Key

使用 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. 设置 Neo4j 向量索引

   // Create vector index for 1536-dimensional OpenAI embeddings
   // If does not works
   CREATE VECTOR INDEX embeddableIndex FOR (n:Document) ON (n.embedding)
   OPTIONS {indexConfig: {
     `vector.dimensions`: 1536,
     `vector.similarity_function`: 'cosine'
   }}
   

5. 启动服务

   # Activate virtual environment
   source .venv/bin/activate  # On Linux/macOS
   # or
   .venv\Scripts\activate     # On Windows
   
   # Start the FastMCP server
   python main.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 密钥	❌	all-MiniLM-L6-v2 model

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 embeddableIndex FOR (n:Document) 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 - 感谢提供协议规范

---