poly query MCP

Poly Query MCP

Poly Query MCP 是一个支持多种数据库查询的MCP(Model Context Protocol)工具，允许您通过MCP协议查询MySQL、PostgreSQL、Redis和MongoDB数据库。

功能特性

• 🔌 多数据库支持: 支持MySQL、PostgreSQL、Redis和MongoDB
• ⚙️ 灵活配置: 支持配置文件和环境变量配置
• 🛡️ 错误处理: 完善的错误处理和异常管理
• 📝 日志记录: 结构化的日志记录系统
• 🔧 MCP协议: 完全兼容MCP协议，可与Claude等AI助手集成

快速开始

安装

使用uv安装（推荐）

# 从PyPI安装
uv add poly-query-mcp

# 或者从GitHub安装
uv add git+https://github.com/yourusername/poly-query-mcp.git

# 或者使用uvx直接运行
uvx poly-query-mcp

传统安装方式

1. 克隆仓库

git clone 
cd poly_query_mcp

1. 创建虚拟环境

python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Linux/Mac

1. 安装依赖

pip install -r requirements.txt

配置

1. 复制示例配置文件

cp config.json config.json

1. 编辑配置文件，添加您的数据库连接信息

使用

启动MCP服务器：

# 使用uvx
uvx poly-query-mcp

# 或者传统方式
python main.py

mcp接入使用：

1. 在支持mcp client中（如Claude Desktop）的配置文件中添加此MCP服务器（参考下面完整的mcp的数据库配置）：

{
  "mcpServers": {
    "poly-query-mcp": {
      "command": "uvx",
      "args": [
        "poly-query-mcp",
        "--mysql-host", "localhost",
        "--mysql-port", "3306",
        "--mysql-user", "root",
        "--mysql-password", "your_mysql_password",
        "--mysql-database", "your_mysql_database"
      ]
    }
  }
}

1. 重启mcp服务
2. 在对话中使用数据库查询功能

更多安装和配置选项请参考 uv安装指南

数据库配置

Poly Query MCP 支持多种配置方式，包括传统配置文件、增强配置文件和环境变量。您可以根据需要选择最适合的配置方式。

1. 直接传入数据库参数

{
  "mcpServers": {
    "poly-query-mcp": {
      "command": "uvx",
      "args": [
        "poly-query-mcp",
        "--mysql-host", "localhost",
        "--mysql-port", "3306",
        "--mysql-user", "root",
        "--mysql-password", "password",
        "--mysql-database", "mysql_database",
        "--postgresql-host", "localhost",
        "--postgresql-port", "5432",
        "--postgresql-user", "postgres",
        "--postgresql-password", "password",
        "--postgresql-database", "postgresql_database",
        "--redis-host", "localhost",
        "--redis-port", "6379",
        "--redis-db", "0",
        "--redis-password", "redis_password",
        "--mongodb-host", "localhost",
        "--mongodb-port", "27017",
        "--mongodb-username", "dev_user",
        "--mongodb-password", "dev_mongodb_password",
        "--mongodb-database", "test"
      ]
    }
  }
}

2. 传统配置文件

创建一个 config.json 文件，包含所有数据库的连接信息：

{
  "mysql": {
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "your_mysql_password",
    "database": "your_mysql_database",
    "charset": "utf8mb4"
  },
  "postgresql": {
    "host": "localhost",
    "port": 5432,
    "user": "postgres",
    "password": "your_postgresql_password",
    "database": "your_postgresql_database",
    "pg_schema": "public"
  },
  "redis": {
    "host": "localhost",
    "port": 6379,
    "db": 0,
    "password": "your_redis_password"
  },
  "mongodb": {
    "host": "localhost",
    "port": 27017,
    "username": "your_mongodb_username",
    "password": "your_mongodb_password",
    "database": "your_mongodb_database"
  }
}

mcp 配置为：

{
  "mcpServers": {
    "poly-query-mcp": {
      "command": "uvx",
      "args": [
        "poly-query-mcp",
        "--config",
        "/path/to/config.json",
      ]
    }
  }
}

3. 增强配置文件（推荐）

增强配置文件支持多环境配置和配置文件，适合复杂的部署场景。创建 config.enhanced.json 文件：

{
  "environments": {
    "development": {
      "mysql": {
        "host": "localhost",
        "port": 3306,
        "user": "root",
        "password": "dev_mysql_password",
        "database": "dev_db",
        "charset": "utf8mb4"
      },
      "postgresql": {
        "host": "localhost",
        "port": 5432,
        "user": "postgres",
        "password": "dev_postgresql_password",
        "database": "dev_db",
        "pg_schema": "public"
      },
      "redis": {
        "host": "localhost",
        "port": 6379,
        "db": 0,
        "password": "dev_redis_password"
      },
      "mongodb": {
        "host": "localhost",
        "port": 27017,
        "username": "dev_user",
        "password": "dev_mongodb_password",
        "database": "dev_db"
      }
    },
    "production": {
      "mysql": {
        "host": "prod-mysql.example.com",
        "port": 3306,
        "user": "app_user",
        "password": "${MYSQL_PROD_PASSWORD}",
        "database": "production_db",
        "charset": "utf8mb4"
      },
      "postgresql": {
        "host": "prod-postgresql.example.com",
        "port": 5432,
        "user": "app_user",
        "password": "${POSTGRESQL_PROD_PASSWORD}",
        "database": "production_db",
        "pg_schema": "public"
      },
      "redis": {
        "host": "prod-redis.example.com",
        "port": 6379,
        "db": 0,
        "password": "${REDIS_PROD_PASSWORD}"
      },
      "mongodb": {
        "host": "prod-mongodb.example.com",
        "port": 27017,
        "username": "app_user",
        "password": "${MONGODB_PROD_PASSWORD}",
        "database": "production_db"
      }
    }
  },
  "profiles": {
    "local": {
      "environment": "development",
      "description": "本地开发环境配置"
    },
    "staging": {
      "environment": "production",
      "description": "预发布环境配置"
    },
    "minimal": {
      "environment": "development",
      "databases": ["mysql"],
      "description": "仅MySQL数据库的轻量级配置"
    }
  },
  "defaults": {
    "environment": "development",
    "log_level": "INFO",
    "connection_pool_size": 5,
    "connection_timeout": 30
  }
}

mcp的配置为：

{
  "mcpServers": {
    "poly-query-mcp": {
      "command": "uvx",
      "args": [
        "poly-query-mcp",
        "--config-enhanced",
        "/path/to/config.enhanced.json",
        "--environment",
        "development"
      ]
    }
  }
}

4. 数据库配置详解

MySQL 配置

使用场景：

• 适用于需要ACID事务支持的关系型数据存储
• 适用于结构化数据，如用户信息、订单数据等

注意事项：

• 确保MySQL用户有足够的权限访问指定的数据库
• 对于生产环境，建议使用SSL连接
• 字符集建议使用utf8mb4以支持完整的Unicode字符集

PostgreSQL 配置

使用场景：

• 适用于需要复杂查询和数据分析的场景
• 适用于需要高级数据类型和扩展功能的应用

注意事项：

• 确保PostgreSQL用户有足够的权限访问指定的数据库和模式
• 对于生产环境，建议配置连接池以优化性能
• 可以通过pg_schema参数实现多租户隔离

Redis 配置

使用场景：

• 适用于缓存、会话存储、消息队列等场景
• 适用于需要高性能读写的数据

注意事项：

• Redis数据库索引范围为0-15，确保指定的索引存在
• 对于生产环境，建议配置密码认证
• 考虑使用Redis集群以提高可用性

MongoDB 配置

使用场景：

• 适用于文档型数据存储，如日志、配置等
• 适用于需要灵活数据结构的场景

注意事项：

• 确保MongoDB用户有足够的权限访问指定的数据库
• 对于生产环境，建议配置副本集以提高可用性
• 考虑使用索引优化查询性能

5. 安全注意事项

1. 密码保护：

- 不要在代码中硬编码密码 - 使用环境变量或配置文件存储敏感信息 - 对于生产环境，考虑使用密钥管理服务

1. 网络安全：

- 在生产环境中使用SSL/TLS连接 - 限制数据库访问的网络范围 - 使用防火墙规则限制数据库访问

1. 权限控制：

- 为应用程序创建专用的数据库用户 - 仅授予必要的最小权限 - 定期轮换数据库密码

8. 故障排除

常见问题

1. 连接超时：

- 检查数据库服务器是否运行 - 验证网络连接和防火墙设置 - 确认主机地址和端口是否正确

1. 认证失败：

- 验证用户名和密码是否正确 - 检查用户是否有访问指定数据库的权限 - 确认认证插件是否匹配

1. 数据库不存在：

- 确认数据库名称是否正确 - 检查用户是否有创建数据库的权限 - 验证数据库是否已创建

支持的数据库

• MySQL
• PostgreSQL
• Redis
• MongoDB

文档

• 安装指南
• API文档
• 开发指南

贡献

欢迎贡献！请查看 贡献指南 了解如何参与项目。

许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。