MCP DB Python

# MCP DB Python MCP DB Python 是一个以 Python 编写的 Model Context Protocol (MCP) 数据库服务，能够通过标准输入/输出上的 JSON-RPC 协议提供安全的数据库结构浏览与查询能力。MCP DB Python is a Python-powered Model Context Protocol (MCP) server that exposes safe database inspection and read-only querying over JSON-RPC via stdin/stdout. ## 项目简介 | Overview 本项目封装了基础的 MCP Server 启动逻辑与数据源适配层，当前聚焦 MySQL，便于在 LLM 工具链中快速调用数据库结构信息与只读查询结果。随着后续维护，接口与数据源适配将持续扩充，帮助更多场景接入 MCP 协议。 This repository packages the core MCP server loop together with database adapters focused on MySQL, making it straightforward to surface schema metadata and read-only query results inside LLM agent workflows. The API surface and connector set will keep expanding as the project is actively maintained. ## 主要特性 | Key Features - 面向 MCP 的 JSON-RPC 通信，兼容多种支持 MCP 的客户端 / MCP-compliant JSON-RPC transport ready for compatible clients. - MySQL 表结构与存储过程元数据查询能力 / Schema and stored procedure introspection for MySQL. - 严格的只读 SQL 校验，保障在线环境安全 / Strict read-only SQL validation to protect production data. - 基于 `.env` 的可配置数据源参数，便于跨环境部署 / `.env`-driven connector settings for seamless environment switching. - 持续维护与扩展，后续将新增更多数据库适配与工具接口 / Actively maintained roadmap toward additional connectors and tools. ## 快速开始 | Quick Start ### 环境要求 | Requirements - Python 3.10 及以上版本 / Python 3.10 or newer. - 可访问的 MySQL 实例（或其他将来扩展的数据源） / Reachable MySQL instance (other engines to be added). ### 安装步骤 | Installation 1. 克隆仓库并进入目录 / Clone the repository and change into the project: ```bash git clone https://github.com/your-account/mcp-db-python.git cd mcp-db-python ``` 2. （可选）创建虚拟环境并激活 / (Optional) Create and activate a virtual environment: ```bash python -m venv venv # Windows .\venv\Scripts\activate # macOS / Linux source venv/bin/activate ``` 3. 安装依赖 / Install dependencies: ```bash pip install -r requirements.txt ``` 4. 配置数据库连接 / Configure database credentials: - 复制或编辑 `.env` 文件，填写 `DB_TYPE`, `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASS`, `DB_NAME`。 Update the `.env` file with the right `DB_TYPE`, `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASS`, and `DB_NAME` values. ### 启动服务 | Run the Server 使用 Python 启动 MCP 服务（默认通过标准输入/输出通讯） / Launch the MCP server (communicates over stdin/stdout): ```bash python server.py ``` 终端会输出 `MCP Python Server started` 等提示，随后即可通过支持 MCP 的客户端或自定义脚本发送 JSON-RPC 请求。 The console logs `MCP Python Server started`, after which MCP-aware clients or custom scripts can exchange JSON-RPC messages with the server. ## 可用接口 | Available Tools | 方法名 / Method | 说明 / Description | 状态 / Status | | --- | --- | --- | | `listTables` | 列出当前数据库中的所有表名 / List every table in the configured database. | 已实现 / Completed | | `getTableSchema` | 返回指定表的字段定义与元数据 / Fetch column metadata for a given table. | 已实现 / Completed | | `runQuery` | 执行仅限只读的 SQL 查询并返回列与数据行 / Execute read-only SQL and return columns with rows. | 已实现 / Completed | | `getProcedureDefinition` | 获取指定存储过程的建造语句 / Retrieve the CREATE statement of a stored procedure. | 已实现 / Completed | | `listDatabases` | 列出当前连接可访问的数据库，方便跨库巡检 / List accessible databases to navigate across schemas. | 已实现 / Completed | | `listViews` | 查找视图名称并返回定义摘要 / Enumerate views with definition snippets. | 已实现 / Completed | | `getTableStats` | 汇总表的行数与数据/索引大小等统计信息 / Return row counts and size statistics for tables. | 已实现 / Completed | | `getIndexInfo` | 查看表上索引的列、类型与唯一性 / Inspect indexes for columns, kinds, and uniqueness. | 已实现 / Completed | | `findForeignKeys` | 列出外键及其关联关系 / List foreign-key constraints and relationships. | 已实现 / Completed | | `getTriggers` | 返回触发器列表与定义 / Fetch trigger listings and definitions. | 已实现 / Completed | | `sampleRows` | 抽样返回指定表的若干数据行 / Sample a handful of rows from a table. | 已实现 / Completed | | `searchColumns` | 关键字搜索列名或注释 / Search column names/comments by keyword. | 已实现 / Completed | | `describeColumn` | 输出字段类型、默认值与约束细节 / Provide type, defaults, and constraint details for a column. | 已实现 / Completed | | `explainQuery` | 对只读 SQL 执行 EXPLAIN，分析执行计划 / Run EXPLAIN on read-only SQL to inspect plans. | 已实现 / Completed | | `listProcedures` | 罗列存储过程或函数名称 / List stored procedures and functions. | 已实现 / Completed | | `listUsers` | 汇总实例中用户与权限信息（需相应权限） / Summarize users and privileges (where permitted). | 已实现 / Completed | | `getServerStatus` | 返回版本、连接数、支持引擎等服务器状态 / Return server status such as version, connections, engines. | 已实现 / Completed | | `compareSchemas` | 比较两个数据库或表的结构差异 / Compare schema structures between databases/tables. | 已实现 / Completed | | `generateDDL` | 输出完整的 CREATE TABLE 语句 / Generate full CREATE TABLE DDL. | 已实现 / Completed | ## 配置说明 | Configuration - `.env` 文件由 `python-dotenv` 自动加载，未配置的项会使用 `config/settings.py` 中的默认值。 The `.env` file is loaded automatically through `python-dotenv`; unset keys fall back to the defaults in `config/settings.py`. - 目前仅实现 MySQL 连接器，若 `DB_TYPE` 非 `mysql` 将抛出 `NotImplementedError`。 MySQL is the only connector implemented today; other `DB_TYPE` values raise `NotImplementedError`. - 根据部署需求可在未来扩展 `db_connectors/` 下的实现并在工具层注册更多方法。 You can extend the `db_connectors/` package and register additional tools as new backends become available. ## 开发计划 | Roadmap - 扩展更多数据库连接器（PostgreSQL、SQLite 等）。 Add new database connectors (PostgreSQL, SQLite, and beyond). - 丰富结构化工具与诊断接口，例如索引分析、表统计等。 Ship more structured utilities such as index analysis or table statistics. - 提供更完善的示例脚本与自动化测试。 Publish richer integration examples and automated tests. 欢迎通过 Issue 或 Pull Request 提出需求；接口会持续完善以覆盖更多数据库运维与数据洞察场景。 Feedback and contributions are welcome—new endpoints will continue to arrive to cover broader database operations and analytics use cases. ## 赞助支持 | Sponsor 如果本项目对你有帮助，欢迎赞助支持后续维护；You can sponsor continued development if this project proves useful: - 扫描下方微信/支付宝赞助码，或通过支付宝账号 `191341025@qq.com` 支持我。 Scan the QR code below (WeChat/Alipay) or tip via Alipay at `191341025@qq.com`.  ## 联系方式 | Contact - Email: tiansenxu@gmail.com - Email: 191341025@qq.com 任何问题、建议或合作意向都可以通过以上邮箱联系，我会尽快回复。 Feel free to reach out with questions, feature requests, or collaboration proposals at the emails above. ## 贡献指南 | Contributing 欢迎提交 Issue 描述使用中的问题，也欢迎直接发起 Pull Request 贡献代码。当前 `main` 分支已开启保护，仅仓库维护者可以直接推送，请从最新 `main` 创建自己的功能分支后再提交 PR；如果你需要在本仓库启用额外的受保护分支，欢迎发送邮件至上述地址与我联系。 Please open issues for bugs or ideas, and submit pull requests if you would like to contribute improvements. The `main` branch is protected and only maintainers can push to it; branch off `main`, work on your feature branch, then open a PR. If you require additional protected branches for collaboration, email me at the contacts above.