mysql-readonly-mcp
Provides read-only access to a MySQL database, with tools for inspecting server information, listing tables and views, describing table structures, listing indexes, running safe read-only SELECT/CTE queries, and viewing JSON EXPLAIN plans, all executed within read-only transactions using a read-only MySQL account.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mysql-readonly-mcp show me the schema of the users table"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mysql-readonly-mcp
本项目是面向个人本机的只读 MySQL MCP Server 首版实现,默认通过 stdio 提供 6 个工具。
工具说明
工具 | 作用 | 主要参数 | 返回内容 |
| 查看当前连接的数据库和 MySQL 服务信息 | 无 | 数据库名、MySQL 版本、字符集、时区及当前安全限制 |
| 列出当前数据库中的表和视图 |
| 表名、对象类型、注释、存储引擎和估算行数 |
| 查看指定表或视图的结构 |
| 字段顺序、字段名、类型、可空性、默认值、主键标识、注释和外键关系 |
| 查看指定表的索引 |
| 索引名、是否唯一、索引类型、字段顺序和前缀长度 |
| 执行一条安全的只读查询 |
| 列信息、二维数据、返回行数、耗时和是否被截断 |
| 查看安全只读查询的 JSON 执行计划 |
| MySQL |
查询工具限制
mysql_query和mysql_explain的sql只允许单条SELECT或只读 CTE。拒绝
INSERT、UPDATE、DELETE、DDL、CALL、SET、跨库引用、多语句、锁定读取、文件导出、用户变量和危险函数。未指定
LIMIT时,服务端自动追加最大返回行数 + 1,用于判断结果是否截断;实际返回不超过配置的最大行数。已有
LIMIT超过最大返回行数时直接拒绝,不自动改写查询语义。成功和失败结果都包含版本化 JSON 结构;同时通过 MCP
structuredContent和精简 JSON 文本返回。
Related MCP server: MySQL MCP Server
连接与调用流程
服务启动和一次工具调用的流程如下:
启动 MCP 进程
│
├─ 读取 .env / 进程环境变量并校验配置
├─ 创建 MySQL 连接池(启动时不主动查询业务数据)
└─ 通过 stdio 等待 MCP 客户端握手
│
├─ 客户端执行 initialize 和 tools/list
└─ 客户端调用具体工具
│
├─ 校验工具参数
├─ mysql_query / mysql_explain:解析并校验只读 SQL
├─ 从连接池获取连接
├─ START TRANSACTION READ ONLY
├─ 设置服务端查询超时并执行 SQL
├─ 成功或失败后执行 ROLLBACK
└─ 返回 structuredContent 和 JSON 文本结果元数据工具使用参数化 SQL 查询 information_schema;mysql_query 和 mysql_explain 使用用户提交的 SQL,但必须先通过 AST 安全策略。查询超时或连接异常时,连接会被销毁而不会放回连接池。服务收到 SIGINT 或 SIGTERM 后关闭连接池。
从项目目录启动开发模式:
Set-Location "C:\Users\77384\WorkProject\mcp\mysql\mysql-readonly-mcp"
npm run dev以 Codex 连接为例
本项目采用 MCP stdio 传输模式。仍然是“本地运行 MCP,Codex 使用 MCP”,但启动动作由 Codex 完成:Codex 作为父进程启动 node dist/index.js,再通过子进程的 stdin/stdout 交换 MCP JSON-RPC 消息。因此,使用 Codex 时不需要提前单独执行 npm run dev。
Codex Desktop、Codex CLI 和 IDE 扩展共享 Codex 配置。完成构建后,在 C:\Users\77384\.codex\config.toml 中配置 MCP,让 Codex 直接启动编译产物:
在项目目录执行
npm install和npm run build。打开
C:\Users\77384\.codex\config.toml,参考 docs/codex-mcp-config.example.toml 增加 MCP 配置。将
env中的MYSQL_HOST、MYSQL_PORT、MYSQL_DATABASE、MYSQL_USER和MYSQL_PASSWORD改为本机测试库配置;密码只保存在本机配置中,不要提交到仓库。重启或重新加载 Codex 的 MCP 配置。Codex 会启动
node dist/index.js,通过 stdin/stdout 完成 MCP 握手和工具调用。
两种启动方式的区别:
npm run dev:你手动启动 MCP,适合本地调试、协议测试或使用 MCP Inspector;该服务只监听当前进程的 stdin/stdout,不会开放端口,Codex 不能再通过端口连接到它。Codex 配置启动:Codex 自动启动 MCP 子进程,并独占这组 stdin/stdout;这是当前项目接入 Codex 的推荐方式。
如果希望“先手动启动 MCP,再由 Codex 连接”,就需要把服务改造成 Streamable HTTP 等网络传输模式,这不是当前项目的实现方式。
config.toml 中的 env 内容写在 [mcp_servers.mysql_readonly.env] 节点下,示例:
[mcp_servers.mysql_readonly]
command = "node"
args = ["C:/Users/77384/WorkProject/mcp/mysql/mysql-readonly-mcp/dist/index.js"]
[mcp_servers.mysql_readonly.env]
MYSQL_HOST = "127.0.0.1"
MYSQL_PORT = "3306"
MYSQL_DATABASE = "erp_0808"
MYSQL_USER = "erp_0808_readonly_user"
MYSQL_PASSWORD = "<只保存在本机配置中的密码>"直接执行 npm run dev 时,才使用项目根目录 .env;Codex 配置中的 env 用于 Codex 通过 stdio 启动 MCP 服务。两者同时存在时,进程环境变量优先于 .env。
示例配置的连接链路是:
Codex
└─ 启动 node <项目绝对路径>/dist/index.js
└─ 通过 config.toml 的 env 传入 MySQL 配置
└─ MCP Server 等待 initialize / tools/list
└─ Codex 调用 mysql_query 等工具
└─ MCP Server 使用只读账号连接 erp_0808Codex 调用工具时,MCP Server 才从连接池获取 MySQL 连接;工具执行完成后回滚只读事务并释放或销毁连接。若只修改源码,需要重新执行 npm run build,再让 Codex 重新加载 MCP Server。
安全边界
服务端只接受单条 SELECT 或只读 CTE。SQL 先经过 node-sql-parser 的 MySQL AST 校验,再在独立 START TRANSACTION READ ONLY 事务中执行。服务端拒绝写操作、管理语句、多语句、跨库引用、锁定读取、文件导出、用户变量赋值和高风险函数。
MySQL 只读账号是最终安全边界。请先参考 docs/mysql-readonly-account.sql,再复制 .env.example 为 .env 填写本机配置。密码不应写入源码、日志或提交记录。
开发与验证
npm install
npm run check
npm test
npm run build
npm start日志只写入 stderr;stdout 保留给 MCP JSON-RPC。Codex 接入配置见 docs/codex-mcp-config.example.toml;JSON 示例仍保留在 docs/codex-mcp-config.example.json,供使用 JSON 格式的其他 MCP 客户端参考。
当前仓库包含不依赖 MySQL 的单元测试。真实 MySQL 8.4 集成测试需要用户提供本机测试库、只读账号和测试数据后执行;本项目默认不会修改数据库。
Available Tools
6 toolsmysql_describe_tableB
Describe columns and foreign-key relationships for one table or view.
Inputs: table (required).
mysql_explainA
Return the JSON execution plan for a safe read-only SELECT query.
Inputs: sql (required).
mysql_get_server_infoA
Return the configured MySQL database, server version, charset, timezone, and safety limits.
Inputs: no named parameters.
mysql_list_indexesA
List indexes and ordered indexed columns for one table.
Inputs: table (required).
mysql_list_tablesC
List tables and views in the configured database.
Inputs: limit, offset, keyword.
mysql_queryB
Execute one safe, read-only SELECT or read-only CTE against the configured database.
Inputs: sql (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a clearly distinct introspection or query concern: server metadata, table listing, column/FK description, index listing, query execution, and plan explanation. The describe_table vs list_indexes boundary is clear (columns vs indexes), so an agent can reliably select the right tool.
All six tools use a consistent mysql_verb_noun snake_case pattern (get_server_info, list_tables, describe_table, list_indexes, query, explain). Predictable and uniform throughout.
Six tools is well-scoped for a read-only database server. Each tool earns its place across discovery (info, tables, describe, indexes) and querying (query, explain) with no redundancy.
The read-only surface covers introspection plus querying and plan analysis, which is solid for the stated purpose. Minor gaps like listing databases or schema-level search exist but are workable given the server targets a single configured database.
Maintenance
Related MCP Connectors
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Read authorized Loam tables and supported external databases through a bounded MCP connection.
SQL validation, formatting, parsing, metadata extraction, linting, and security analysis.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables safe querying and optional writing to MySQL databases via MCP tools, with support for schema inspection, connection management, and read-only mode.16 npm3MIT
- AlicenseCqualityDmaintenanceConnects MCP-compatible clients like Claude to a MySQL database, enabling schema inspection and read/write queries via stdio transport.51MIT
- AlicenseNot gradedqualityDmaintenanceProvides read-only access to MySQL databases, enabling schema exploration, table inspection, and safe SELECT query execution via MCP.1ISC
- AlicenseAqualityCmaintenanceRead-only MySQL database access via MCP. Enables listing databases, tables, schemas, running SELECT queries, and EXPLAIN plans.6MIT