MySQL MCP Server
Provides a secure gateway for AI agents to access MySQL databases, supporting read/write operations with risk-level gating, AST-based validation, and full audit trails.
Click on "Install 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 MCP Serverlist all tables in the database"
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 MCP Server
AI-to-DB Secure Gateway — 不只是一个 MCP Server,而是 AI 与数据库之间的安全执行网关。
基于 NestJS + TypeScript 构建,通过 MCP 协议为 Claude Code 等 AI 助手提供对 MySQL 数据库的受控访问能力。核心目标是在 AI 的灵活性与数据库的安全性之间建立可信边界。
设计理念
传统数据库工具直接暴露执行能力,对 AI 调用者而言风险极高。本项目的核心设计原则:
最小权限:工具按风险分级,高危操作默认关闭
AST 级校验:不依赖关键字匹配,通过 SQL Parser 解析语法树做严格校验
可审计:每次操作完整记录,行为可追溯
可控执行:AI 可以分析(EXPLAIN)但不能随意破坏
Related MCP server: MySQL MCP Server
快速开始
npm install
cp .env.example .env
# 编辑 .env 填入 MySQL 连接信息
npm run start:dev # 开发模式
npm run build # 构建
npm run start:prod # 生产运行在 Claude Code 中配置
先构建项目:
npm run build使用 claude mcp add 命令注册(推荐,写入用户级全局配置):
claude mcp add mysql node /path/to/mysql-mcp-nest/dist/main.js \
--scope user \
-e DB_HOST=127.0.0.1 \
-e DB_PORT=3306 \
-e DB_USER=root \
-e DB_PASSWORD=your_password \
-e DB_DATABASE=your_database \
-e PERMISSION_MODE=read_write \
-e AUDIT_LOG_ENABLED=true \
-e AUDIT_LOG_DIR=/path/to/mysql-mcp-nest/logs--scope user:写入~/.claude.json,所有项目均可使用--scope project:写入当前项目的.claude.json,仅当前项目可用
注册后重启 claude,执行 /mcp 验证连接状态:
❯ /mcp
mysql connected在 Codex 中配置
先构建项目:
npm run build使用 codex mcp add 命令注册到 Codex:
codex mcp add mysql \
--env DB_HOST=127.0.0.1 \
--env DB_PORT=3306 \
--env DB_USER=root \
--env DB_PASSWORD=your_password \
--env DB_DATABASE=your_database \
--env PERMISSION_MODE=read_write \
--env AUDIT_LOG_ENABLED=true \
--env AUDIT_LOG_DIR=/path/to/mysql-mcp-nest/logs \
-- node /path/to/mysql-mcp-nest/dist/main.js验证配置是否写入成功:
codex mcp list
codex mcp get mysql注册后重启 Codex,或重新开启一个 Codex 会话,让 MCP 配置生效。
连接成功后即可直接使用:
列出 your_database 中的所有表在 Cursor 中配置
项目已包含 .cursor/mcp.json,Cursor 打开本仓库后会注册 mysql MCP Server:
{
"mcpServers": {
"mysql": {
"type": "stdio",
"command": "node",
"args": ["${workspaceFolder}/dist/main.js"],
"envFile": "${workspaceFolder}/.env",
"env": {
"AUDIT_LOG_DIR": "${workspaceFolder}/logs"
}
}
}
}使用前先构建项目,并确认 .env 里已填好 MySQL 连接信息:
npm run build然后重启 Cursor,或在 Cursor Settings → MCP 中刷新/启用 mysql。
Available Tools
6 toolsmysql_describe_tableA
Get column structure, indexes, and CREATE statement for a table.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | Table name | |
| database | Yes | Database name |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. 'Get' implies read-only, but it does not mention error behavior on missing tables, permission requirements, or compatibility with views. It leaves room for ambiguity, though the read-only implication is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff. It is front-loaded with the verb and clearly conveys the tool's output, making it efficient to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description provides a useful summary of the return contents (column structure, indexes, CREATE statement). However, it omits details about return format, error handling, or operational nuances, leaving moderate gaps for a simple describe tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters (database and table), so schema coverage is 100%. The description only repeats 'for a table' and adds no extra parameter semantics, so it relies entirely on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' and names three concrete outputs (column structure, indexes, CREATE statement) for a table. This clearly distinguishes it from siblings like mysql_query (arbitrary queries) and mysql_list_tables (just table names).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. It does not mention use cases, when not to use it, or recommend alternatives such as mysql_query or mysql_list_tables, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mysql_executeA
[riskLevel: medium] Execute an INSERT, UPDATE, or DELETE statement. UPDATE/DELETE without WHERE are rejected by default.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | DML statement. Use ? as placeholders. | |
| params | No | Values for ? placeholders | |
| database | No | Target database (optional) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a medium risk level and the default rejection of UPDATE/DELETE without WHERE, which is valuable safety behavior. However, it does not explain return values, transaction semantics, or whether the 'by default' can be overridden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundant information. The risk level is front-loaded, and the key safety behavior is immediately stated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and a key safety rule, but for a mutation tool it lacks information about return values, error handling, or transactional behavior. The schema covers parameters well, but the absence of output schema and annotations leaves some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all three parameters (sql, params, database) with 100% coverage, so the description adds no additional parameter details. Per the rubric, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Execute' and explicitly names the DML statement types (INSERT, UPDATE, DELETE), clearly distinguishing it from sibling tools like mysql_query (likely for reads). It also adds a useful safety constraint about WHERE-clause rejection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for write operations by enumerating INSERT, UPDATE, DELETE, which contrasts with read-oriented sibling tools. It does not explicitly name alternative tools or state when not to use, but the operation types provide clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mysql_explainA
Run EXPLAIN on a SELECT statement to analyze query performance. Returns execution plan and full-scan warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | SELECT statement to analyze | |
| database | No | Target database (optional) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It reveals the return value (execution plan and full-scan warnings) but does not explicitly state that the query is not executed or that data is unchanged. This is a notable gap for an AI agent that might need to know the operation is non-destructive. The read-only nature is implied by 'EXPLAIN' but not explicitly confirmed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the action and purpose, and then details the return value. Every word earns its place, with no unnecessary detail or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters and no output schema, the description is mostly complete: it states the action, scope, and return type. It misses the explicit note that the SELECT is not executed, which would be helpful for safety awareness, but otherwise covers the essential context well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%: the sql parameter is described as 'SELECT statement to analyze' and database as 'Target database (optional).' The tool description adds no further parameter semantics, so the baseline of 3 applies since the schema already documents both parameters effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Run EXPLAIN on a SELECT statement to analyze query performance,' which clearly identifies the specific verb (run EXPLAIN), resource (SELECT statement), and purpose (query performance). It distinguishes itself from siblings like mysql_query and mysql_execute by focusing on analysis rather than execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'analyze query performance' sets a clear context for when to use this tool: when you need to inspect the execution plan or check for full-scan warnings. It does not explicitly mention alternatives or exclusions, but the context is sufficient to infer it should be used over direct query execution for performance analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mysql_list_databasesA
List all accessible databases (system databases are excluded).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It adds a behavioral detail (excludes system databases) but does not disclose return format, error cases, or explicitly confirm it is a read-only operation. For a listing tool, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core purpose and a key behavioral constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is slightly under-specified. It does not mention what the returned data looks like (e.g., a list of strings) or potential errors, but for a simple list tool, the information provided is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so the schema fully documents inputs. Baseline for 0 params is 4; the description adds no parameter information but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('list') and resource ('databases'), and adds scope ('all accessible') and an exclusion ('system databases are excluded'). This clearly distinguishes it from sibling tools like mysql_list_tables or mysql_describe_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need to list accessible databases) but does not explicitly mention alternatives or when-not-to-use. Sibling tools like mysql_list_tables make the purpose contextually clear, but no direct guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mysql_list_tablesB
List all tables in a database.
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes | Database name |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the function, without disclosing behavioral details like return format, inclusion of views, behavior on missing databases, or that it is a read-only operation. The verb 'list' implies non-destructive but is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundant wording, making it appropriately sized for a simple listing tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, the description is minimally sufficient. However, it does not explicitly state the return value (e.g., an array of table names) or any edge case behavior, leaving some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no meaning beyond the schema's 'Database name' parameter. Schema coverage is 100%, so the baseline 3 is appropriate; the description does not compensate with additional parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'list' and resource 'tables' with a scope 'in a database', clearly distinguishing it from siblings like mysql_list_databases (lists databases) and mysql_describe_table (describes a single table).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus siblings, such as before querying or for enumeration. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mysql_queryB
Execute a SELECT query against MySQL. Returns rows, field names, and row count. Results are automatically limited.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | SELECT statement. Use ? as placeholders. | |
| limit | No | Max rows to return (default 100, max 1000) | |
| params | No | Values for ? placeholders | |
| database | No | Target database (optional) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must convey safety and operational behavior. It states the operation is a SELECT query (non-destructive) and that results are automatically limited, which are useful behavioral traits. However, it doesn't explicitly state it is read-only, doesn't mention the default/max limit values (though schema does), and doesn't discuss any potential error conditions or permission requirements. The description adds some transparency but is not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each providing essential information: the operation, the return payload, and the auto-limit behavior. No superfluous language; it is easy to scan and immediately communicates the tool's core purpose and caveat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with full schema descriptions and no output schema, the description gives a clear summary of return values (rows, field names, row count) and the auto-limit behavior, which is the key operational constraint. However, it lacks any mention of the relationship to sibling tools (e.g., mysql_execute for writes), which would complete the context. Overall, it covers the most important aspects well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so every parameter (sql, limit, params, database) has a description. The description adds no additional parameter semantics, so baseline 3 is appropriate. It does mention that results are returned, but not specific to parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a SELECT query and returns structured results (rows, field names, row count). It uses the specific verb 'Execute' and resource 'SELECT query against MySQL', but does not explicitly differentiate from sibling tools like mysql_execute, though 'SELECT' narrows the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives. It implies it is for SELECT queries but never mentions that mysql_execute handles write operations or other non-SELECT statements. There are no explicit exclusions or comparable use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
6 tool updates
v1.0.0- First observed
mysql_describe_table - First observed
mysql_execute - First observed
mysql_explain - First observed
mysql_list_databases - First observed
mysql_list_tables - First observed
mysql_query
TDQS
Scored across 6 tools
Each tool targets a distinct operation (query, explain, list databases, list tables, describe table, execute DML). No overlap in purpose or usage.
All tool names follow a consistent 'mysql_' prefix with verb_noun snake_case (mysql_query, mysql_explain, mysql_list_databases, etc.). Uniform and predictable.
Six tools is well within the ideal 3-15 range. Each tool provides a clear, necessary capability for a MySQL server without redundancy.
The surface covers query execution, performance analysis, schema exploration (databases, tables, describe), and DML operations. Minor gap: no DDL (create/alter/drop) or transaction control, but for a focused MySQL MCP server the coverage is good.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
AI agents propose database changes as reviewable requests — no direct write access.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables natural language database operations on MySQL databases with AI integration, supporting CRUD operations, schema inspection, and audit logging with built-in security features including SQL injection protection and permission controls.220MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to securely interact with MySQL databases for schema discovery, data querying, and record management with configurable access controls. It provides specialized tools for listing tables, describing structures, and performing CRUD operations within environments like Claude and VS Code.13MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI tools to interact with MySQL databases through natural language, including schema browsing, queries, CRUD operations, with destructive actions gated behind user approval.77MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants like Claude to interact with MySQL databases through a standardized protocol, supporting schema inspection, query execution, and data manipulation with safety controls.1-