AI导哈

数据库查询协议服务器

QueryCraftMCP是一个灵活的模型上下文协议（MCP）服务器，旨在连接大型语言模型（LLM）和各种数据库系统，支持动态发现数据库模式、执行查询和通过标准化协议检索数据。

  • by ratchanonth60
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 ratchanonth60/querycraftmcp

使用说明

查询CraftMCP

QueryCraftMCP是一个灵活的模型上下文协议（MCP）服务器，旨在弥合大型语言模型（LLM）和各种数据库系统之间的差距。它允许LLM或其他MCP客户端通过标准化协议动态发现数据库模式、执行查询和检索数据。服务器支持多个数据库后端（目前是PostgreSQL和SQLite），可通过配置进行选择。

特性

  • 多数据库后端支持：
    • PostgreSQL： 异步交互使用 asyncpg，包括通过生命周期管理实现连接池。
    • SQLite： 使用内置的同步交互 sqlite3 图书馆。
    • 使用易于配置的活动后端 ACTIVE_DB_BACKEND 环境变量。
  • 动态工具加载： 工具和数据库连接寿命根据配置的后端动态加载。
  • 全面的数据库交互工具：
    • 架构发现： 列出可用数据库（PostgreSQL）、数据库对象（表/视图）（PostgreSQL）和对象列（PostgreSQL）的工具。对于SQLite，提供了一个检索全表DDL模式的工具。
    • 数据查询：
      • 结构化搜索能力（例如。， search_data PostgreSQL）。
      • 原始SQL查询执行（例如。， execute_raw_sql 对于PostgreSQL， execute_query 对于SQLite），出于安全考虑。
  • 寿命管理： 在整个应用程序生命周期中对数据库连接进行稳健管理。
  • 传输协议： 利用服务器发送事件（SSE）进行MCP通信。
  • 配置： 主要通过 .env 文件和环境变量。
  • Docker支持： 包括a Dockerfile （在讨论中建议，未上传），便于容器化和部署。

项目结构

该项目遵循 src/ 布局，特定于数据库的实现按以下方式组织 src/db_backends/:

QueryCraftMCP/
├── src/
│   ├── init.py
│   ├── main.py                 # Main application entry point
│   │
│   └── db_backends/
│       ├── init.py
│       ├── postgres/           # PostgreSQL specific modules
│       │   ├── init.py
│       │   ├── lifespan.py
│       │   ├── schema_tools.py
│       │   └── query_tools.py
│       └── sqlite/             # SQLite specific modules
│           ├── init.py
│           ├── lifespan.py

│           ├── schema_tools.py
│           └── query_tools.py
│
├── .env                        # For local environment variables
├── requirements.txt

├── Dockerfile                  # For building Docker images (example provided in discussion)
└── .dockerignore               # Specifies files to ignore in Docker build (example provided in discussion)
└── README.md

先决条件

  • Python 3.9+
  • Docker（如果通过Docker运行）
  • 访问PostgreSQL服务器（如果使用PostgreSQL后端）
  • SQLite数据库文件的可写目录（如果使用SQLite后端）

设置

  1. 克隆存储库：

    git clone <your-repository-url>
cd QueryCraftMCP

  2. 创建虚拟环境（推荐）：

    python -m venv venv
source venv/bin/activate  # On Linux/macOS
# venv\Scripts\activate    # On Windows

  3. 安装依赖关系：

    pip install -r requirements.txt

    依赖关系包括 mcp[cli], asyncpg，以及 python-dotenv.

  4. 配置环境变量： 创建一个 .env 项目根目录中的文件。用必要的配置填充它：

    # .env

# --- General Configuration ---
# Choose the active database backend: "postgres" or "sqlite"
ACTIVE_DB_BACKEND="postgres"

# MCP Server Host and Port (used by main.py)
MCP_HOST="0.0.0.0"
MCP_PORT="8888" # The port your MCP server will listen on with SSE/HTTP

# --- PostgreSQL Backend Configuration ---
# Required if ACTIVE_DB_BACKEND is "postgres"
POSTGRES_DATABASE_URL="postgresql://your_user:your_password@your_pg_host:5432/your_database"

# --- SQLite Backend Configuration ---
# Required if ACTIVE_DB_BACKEND is "sqlite"
# This path is relative to where the application runs.
# If running in Docker, this path will be inside the container.
SQLITE_DATABASE_PATH="querycraft_data.db"
    • 替换占位符值（如 your_user, your_password等）与您的实际凭据和路径。
    • 这 MCP_HOST 和 MCP_PORT 被使用 FastMCP 当它在中实例化时 main.py.

运行应用程序

1.本地（直接使用Python）

确保您的 .env 文件配置正确。

python -m src.main

服务器将开始使用配置的ACTIVE_DB_BACKEND，并将使用SSE传输在MCP_host和MCP_port（默认为0.0.0.0:8888）指定的主机和端口上进行侦听。

  1. 使用Docker 首先，构建Docker镜像（假设你有一个像前面讨论中建议的那样的Docker文件）：
docker build -t querycraftmcp .

然后，运行Docker容器。您需要传递环境变量。

PostgreSQL后端示例：

docker run -it --rm \
  -p 8888:8888 \
  -e ACTIVE_DB_BACKEND="postgres" \
  -e POSTGRES_DATABASE_URL="postgresql://docker_user:docker_pass@host.docker.internal:5432/docker_db" \
  -e MCP_HOST="0.0.0.0" \
  -e MCP_PORT="8888" \
  querycraftmcp
  • 用实际的PostgreSQL凭据替换docker_user、docker_pass、docker_db。
  • host.docker.internal可用于从docker容器（适用于Mac/Windows的docker Desktop）连接到主机上运行的PostgreSQL服务器。
  • -p 8888:8888 将主机的端口映射到容器的端口。

相关 MCP