使用说明

🔍 MCP服务器-矢量搜索

闪电般的速度 模型上下文协议（MCP）服务器 建造于 FastMCP 它将Neo4j的图形数据库功能与使用嵌入的高级向量搜索无缝结合。该服务器支持在您的知识图中进行智能语义搜索，使您能够以闪电般的速度通过自然语言查询发现与上下文相关的信息。

🏗️ 建筑

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

🚀 快速开始

先决条件

Python 3.8+
紫外线
Neo4j数据库 （v5.0+）带APOC插件
OpenAI API密钥

紫外线安装

安装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"

克隆并设置项目

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

环境配置

# 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

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'
}}

启动服务器

# 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要求

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

性能优化

紫外线益处：与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"
      }
    }
  }
}

🐛 故障排除

常见问题

“找不到模块”错误

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

“找不到矢量索引”

// 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'}}

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!')
"

🤝 贡献

分叉存储库
创建要素分支： git checkout -b feature/amazing-feature
安装开发依赖项： uv pip install -e ".[dev]"
进行更改并添加测试
承诺： git commit -m 'Add amazing feature'
推： git push origin feature/amazing-feature
打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

FastMCP -对于令人难以置信的MCP框架
紫外线 -用于快速Python包管理
Neo4j -强大的图形数据库功能
OpenAI -用于最先进的嵌入模型
模型上下文协议 -协议规范

🚀 Made with ❤️ for the AI and Graph Database community

⬆️ Back to Top