db-connect-mcp

使用说明（简要概要，便于开发者快速上手）

• 项目简介

  • db-connect-mcp 是一个基于 MCP 的后端服务器，面向 PostgreSQL、MySQL/MariaDB 与 ClickHouse，提供统一的、可扩展的上下文服务，用于在 LLM 的对话中访问数据库资源、执行只读工具、渲染和提供 Prompt 模板等。
  • 通过 JSON-RPC 的 MCP 协议与客户端通信，服务器端负责会话管理、能力声明以及对资源、工具和 Prompts 的渲染与分发。

• 主要功能点

  • 资源管理与数据访问：提供数据库的结构信息、表、列、索引、约束、以及简单的数据读取能力（只读模式）。
  • 工具注册与执行：暴露一组工具（如 list_schemas、list_tables、describe_table、analyze_column、sample_data、execute_query、get_table_relationships 等），LLM 客户端可调用外部功能。
  • Prompt 模板与渲染：支持以 Prompt 模板形式定义与渲染对话所需的指令与上下文内容。
  • MCP 协议支持：实现 MCP 的核心请求/响应处理，包含错误处理与数据序列化，输出符合 TextContent/JSON 风格。
  • 多传输协议支持：同时提供标准输入输出（stdio）和基于 HTTP 的 StreamableTransport（如 Streamable HTTP）。
  • 安全与合规：默认只读访问，查询与修改语句的严格校验，限制返回数据量，支持 SSH 隧道访问后端数据库。

• 安装步骤

  • 依赖环境：Python 3.10+，以及一个或多个数据库实例（PostgreSQL、MySQL/MariaDB、ClickHouse）。
  • 安装命令（对开发者友好）：通过 PyPI 安装后即可运行。
  • 运行方式示例：直接通过 Python 模块运行，或者在现有环境中以服务器形式启动。

• 服务器配置（给 MCP 客户端的配置信息，json 格式，含 server 名称、启动命令与参数等）

  • 说明：以下配置场景用于 Claude 等 MCP 客户端对接，确保 MCP 客户端能够正确发现并启动对应的 MCP 服务器实例。注意：客户端只需要读取该配置，不需要修改服务器端实现代码。
  • 配置示例（文本描述，不以代码块呈现，请按此结构理解并填充到您的客户端配置中）：
    • server name: db-connect-mcp
    • command: python
    • args: ["-m", "db_connect_mcp"] // 启动服务器的模块入口
    • env（可选，环境变量）:
      • DATABASE_URL: 指向目标数据库的连接字符串，例如 postgresql+asyncpg://user:pass@host:5432/dbname
      • SSH_HOST/SSH_PORT/SSH_USERNAME 等（如果需要通过 SSH 隧道访问数据库）
      • 其他如 SECRET_KEY、MCP 配置相关变量按需要添加
    • 说明：该配置用于客户端在本地或远程环境中启动 MCP 服务器进程，客户端将通过 MCP 协议与服务器对话，获取资源、调用工具、执行查询等能力。
  • 关键信息点
    • 服务器名称要唯一，便于在客户端进行管理。
    • 启动命令要确保在目标环境中可执行（如 vil PATH 问题时用 python -m 模块形式）。
    • 环境变量应包含数据库连接信息与可选的隧道配置信息，以便客户端实现透明的隧道访问。
  • 附注
    • 客户端无需修改服务器代码，仅通过上述配置连接和管理 MCP 服务器。

• 基本使用方法

  • 启动服务器后，客户端可以通过 MCP 协议调用工具（如 list_schemas、list_tables、describe_table、execute_query 等）来获取数据库元数据、执行只读查询、并获取结构化的结果。
  • 结合野心：将服务器与 Claude/其它 LLM 平台对接后，可以在自然语言对话中完成跨数据库的数据探索、分析和展示。