pgvector Azure OpenAI MCP服务器
一个具有RAG功能的MCP服务器，使用Azure OpenAI嵌入和PostgreSQL的pgvector。
专注于Azure OpenAI嵌入。
特性
- MCP兼容：完全基于模型上下文协议，与人工智能助手无缝集成。
- 馆藏管理：创建、列出、重命名和删除向量集合。
- 向量运算：添加向量，搜索相似内容，批量处理文档。
- 嵌入服务：集成Azure OpenAI嵌入。
- 现代包装管理：基于uv包管理器，用于快速安装和依赖关系管理。
- 原子操作：数据库事务确保了集合重命名等操作的原子性。
- 与跨平台支持：与Windows、macOS和Linux兼容。
快速开始
1.安装方法
方法1：直接用uvx运行（最推荐）
# No installation required, run directly with uvx in MCP configuration
# uvx will automatically download and manage packages方法2：使用紫外线进行安装
# Global tool installation
uv tool install pgvector-azure-openai-mcp-server
# Or project dependency installation
uv add pgvector-azure-openai-mcp-server方法3：使用pip进行安装
pip install pgvector-azure-openai-mcp-server2.使用Docker设置数据库
使用 docker-compose.yaml 使用以下命令设置数据库 pgvector 支持。
安装 pgvector 在数据库中，a init-db.sql 脚本必须在PostgreSQL容器首次运行时运行。下载这个 init-db.sql 先写脚本：
wget https://raw.githubusercontent.com/darktohka/pgvector-azure-openai-mcp-server/refs/heads/master/init-db.sql然后，创建 docker-compose.yaml:
services:
db:
image: pgvector/pgvector:pg18
restart: always
environment:
POSTGRES_DB: mcp_vectors
POSTGRES_USER: username
POSTGRES_PASSWORD: password
ports:
- '5432:5432'
volumes:
- db_data:/var/lib/postgresql/data
- ./init-db.sql:/docker-entrypoint-initdb.d/init-db.sql:ro
volumes:
db_data:要创建数据库，最后：
docker compose up -d默认情况下 mcp_vectors 将使用Postgres数据库。
如果数据库需要手动设置（使用时不需要 init-db.sql)，使用：
# Connect to PostgreSQL and enable the pgvector extension
psql postgres -c "CREATE EXTENSION IF NOT EXISTS vector;"3.配置MCP客户端
将以下配置添加到MCP客户端配置文件中（例如，VS代码）：
推荐配置（使用uvx，无需预安装）:
{
"servers": {
"pgvector-azure-openai-mcp-server": {
"command": "uvx",
"args": ["pgvector-azure-openai-mcp-server"],
"env": {
"DATABASE_URL": "postgresql://username:password@localhost:5432/mcp_vectors",
"AZURE_OPENAI_API_KEY": "your_azure_openai_api_key_here",
"AZURE_OPENAI_ENDPOINT": "your_azure_openai_endpoint_here",
"AZURE_OPENAI_MODEL": "text-embedding-3-small",
"DEBUG": "false"
}
}
}
}替代配置（如果已安装）:
{
"servers": {
"pgvector-azure-openai-mcp-server": {
"command": "pgvector-azure-openai-mcp-server",
"env": {
"DATABASE_URL": "postgresql://username:password@localhost:5432/mcp_vectors",
"AZURE_OPENAI_API_KEY": "your_azure_openai_api_key_here",
"AZURE_OPENAI_ENDPOINT": "your_azure_openai_endpoint_here",
"AZURE_OPENAI_MODEL": "text-embedding-3-small",
"DEBUG": "false"
}
}
}
}传统配置（使用Python模块）:
{
"servers": {
"pgvector-azure-openai-mcp-server": {
"command": "python",
"args": ["-m", "pgvector_azure_openai_mcp_server"],
"env": {
"DATABASE_URL": "postgresql://username:password@localhost:5432/mcp_vectors",
"AZURE_OPENAI_API_KEY": "your_azure_openai_api_key_here",
"AZURE_OPENAI_ENDPOINT": "your_azure_openai_endpoint_here",
"AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME": "your_embedding_deployment_name_here",
"DEBUG": "false"
}
}
}
}警告：使用Claude Code时，顶级密钥被调用 mcpServers 不 servers.
4.验证安装
使用MCP客户端调用 status 用于验证连接的工具：
{
"tool": "status",
"parameters": {}
}预期响应：
{
"success": true,
"database": {
"connected": true,
"pgvector_installed": true
},
"embedding_service": {
"available": true,
"provider": "Azure OpenAI"
}
}MCP工具参考
pgvector MCP服务器为MCP客户端提供了以下10个工具：
1.系统状态检查
{
"tool": "status",
"parameters": {}
}2.收款管理
创建集合
{
"tool": "create_collection",
"parameters": {
"name": "my_documents",
"description": "My document collection",
"dimension": 1536
}
}列出所有收藏
{
"tool": "list_collections",
"parameters": {
"include_documents": true
}
}查看收藏详细信息
{
"tool": "show_collection",
"parameters": {
"name": "my_documents",
"include_stats": true
}
}重命名集合（新功能）
{
"tool": "rename_collection",
"parameters": {
"old_name": "my_documents",
"new_name": "document_library"
}
}删除收藏
{
"tool": "delete_collection",
"parameters": {
"name": "my_documents",
"confirm": true
}
}3.矢量运算
添加文本矢量
{
"tool": "add_text",
"parameters": {
"collection_name": "my_documents",
"text": "This is a sample document content",
"metadata": {
"source": "manual",
"type": "document",
"category": "Technical Documentation"
}
}
}搜索类似内容
{
"tool": "search_collection",
"parameters": {
"collection_name": "my_documents",
"query": "Machine learning related content",
"limit": 5,
"search_strategy": "smart",
"min_similarity": 0.7
}
}添加文档文件
{
"tool": "add_document",
"parameters": {
"collection_name": "my_documents",
"file_path": "/path/to/document.pdf",
"metadata": {
"category": "manual",
"language": "en"
}
}
}删除向量
{
"tool": "delete_vectors",
"parameters": {
"collection_name": "my_documents",
"file_path": "/path/to/old_document.pdf",
"confirm": true
}
}使用示例
基本工作流程
通过MCP客户端按顺序调用以下工具：
// 1. Check system status
{
"tool": "status",
"parameters": {}
}
// 2. Create document collection
{
"tool": "create_collection",
"parameters": {
"name": "documents",
"description": "Document knowledge base"
}
}
// 3. Add document content
{
"tool": "add_text",
"parameters": {
"collection_name": "documents",
"text": "Machine learning is an important branch of artificial intelligence",
"metadata": {"type": "knowledge"}
}
}
// 4. Search for relevant content
{
"tool": "search_collection",
"parameters": {
"collection_name": "documents",
"query": "Deep learning",
"limit": 3
}
}
// 5. View collection statistics
{
"tool": "show_collection",
"parameters": {
"name": "documents",
"include_stats": true
}
}文档处理示例
// Process PDF document
{
"tool": "add_document",
"parameters": {
"collection_name": "tech_docs",
"file_path": "/Users/username/documents/manual.pdf",
"metadata": {
"category": "technical",
"language": "en",
"source": "official_docs"
}
}
}
// Search document content
{
"tool": "search_collection",
"parameters": {
"collection_name": "tech_docs",
"query": "API configuration method",
"search_strategy": "smart",
"metadata_filters": {
"category": "technical"
}
}
}集合重命名和管理示例
// Rename collection (new feature)
{
"tool": "rename_collection",
"parameters": {
"old_name": "temp_docs",
"new_name": "permanent_docs"
}
}
// List all collections
{
"tool": "list_collections",
"parameters": {
"include_documents": true
}
}
// Delete unnecessary vectors
{
"tool": "delete_vectors",
"parameters": {
"collection_name": "permanent_docs",
"file_path": "/old/path/outdated.pdf",
"confirm": true
}
}功能描述
Windows编码兼容性
- 自动编码检测：支持GBK、GB2312、UTF-8和其他编码格式。
- 编码转换：自动转换为UTF-8进行统一处理。
搜索策略
- 聪明的：SQL+语义搜索的智能组合（推荐）。
- 仅限sql_only：仅使用传统的SQL文本搜索。
- 仅限语义：仅使用向量相似性搜索。
原子运行保证
- 集合重命名：数据库事务确保操作的原子性。
- 批量插入：保证矢量数据批处理过程中的一致性。
- 错误恢复：操作失败时自动回滚，以确保数据完整性。
性能优化
- 矢量索引：使用pgvector的ivfflat索引来优化搜索性能。
- 批处理：支持文档分块和批量向量生成。
- 连接池：SQLAlchemy连接池提高了数据库访问效率。
- 响应时间：文档处理的目标响应时间\<2秒。
系统要求
- python：3.11+（使用现代Python功能）
- PostgreSQL：16+，启用pgvector扩展
- pg载体：版本0.8.0+
- MCP客户端：支持MCP协议的AI助手（例如Claude Desktop）
- 包管理：uv（推荐）或pip
- Azure OpenAI API：用于文本嵌入的Azure OpenAI API密钥
开发和部署
uv项目开发
# Clone the project
git clone https://github.com/darktohka/pgvector-azure-openai-mcp-server
cd pgvector-azure-openai-mcp-server
# Install dependencies with uv
uv sync
# Run tests
uv run pytest
# Build package
uv build
# Publish to PyPI
uv publish环境变量配置
# Required configuration
DATABASE_URL=postgresql://username:password@localhost:5432/database
AZURE_OPENAI_API_KEY=your_api_key_here
AZURE_OPENAI_ENDPOINT=your_azure_openai_endpoint_here
AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME=your_embedding_deployment_name_here
# Optional configuration
DEBUG=false # Debug mode安装和配置说明
uvx方法的优点
- 无需预安装：uvx自动下载和管理包及其依赖关系。
- 孤立的环境：每个工具都在独立的环境中运行，避免了依赖冲突。
- 自动更新：始终使用最新版本。
- 简化配置：配置文件更简单，不需要指定路径。
配置选择建议
- 新用户：建议使用uvx配置，它是最简单、最快的。
- 开发者：安装
uv tool install然后直接调用命令。 - 生产环境：可以选择传统的Python模块方法进行版本控制。
故障排除
常见问题:
- 数据库连接失败：请检查Database_URL格式和PostgreSQL服务状态。
- 找不到pgvector扩展名：执行
CREATE EXTENSION vector;在PostgreSQL中。确保init-db.sql正在运行。 - API密钥错误：验证是否
AZURE_OPENAI_API_KEY,AZURE_OPENAI_ENDPOINT，以及AZURE_OPENAI_MODEL配置正确。 - 集合重命名失败：检查新名称是否已存在。
- uvx网络问题：确保网络连接正常，uvx需要从PyPI下载包。