MySQL MCP Server
A production-ready Model Context Protocol (MCP) server for MySQL database integration with AI agents
Last Updated: 2026-10-26 16:39:47
Agenten stärken
Der eigene Befehl des Herausgebers. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
npx -y @berthojoris/[email protected]Claude Code hat keinen Installationslink für einen lokalen Befehl. Kopieren Sie den Befehl unten und führen Sie ihn in einem Terminal aus.
claude mcp add berthojoris-mcp-mysql-server -- npx -y @berthojoris/mcp-mysql-server@1.46.0In einem Terminal ausführen.
{ "mcpServers": { "berthojoris-mcp-mysql-server": { "command": "npx", "args": [ "-y", "@berthojoris/[email protected]" ] } }}claude_desktop_config.json
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenRun directly with npx:
npx @berthojoris/mcp-mysql-server mysql://user:pass@localhost:3306/mydb "list,read,utility"
Add to your AI agent config (.mcp.json, .cursor/mcp.json, etc.):
{
"mcpServers": {
"mysql": {
"command": "npx",
"type": "stdio",
"args": [
"-y",
"@berthojoris/mcp-mysql-server",
"mysql://user:pass@localhost:3306/mydb",
"list,read,utility"
]
}
}
}
For dual-layer and environment-variable configuration, see DOCUMENTATIONS.md → Configuration. To connect remote clients such as ChatGPT over HTTP, see Remote Access.
No installation required - run directly:
npx @berthojoris/mcp-mysql-server mysql://user:pass@localhost:3306/db "list,read,utility"
npm install -g @berthojoris/mcp-mysql-server
mcp-mysql mysql://user:pass@localhost:3306/db "list,read,utility"
Credentials with special characters: if your username or password contains characters that have a special meaning in URLs (
@,:,/,?,#,%,&, etc.), URL-encode them before putting them in the connection string. For example, the passwordp@ss:w0rdbecomesp%40ss%3Aw0rd, givingmysql://user:p%40ss%3Aw0rd@host:3306/db. The server decodes both the username and password before connecting.
Create .env file for local development:
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=yourpassword
DB_NAME=yourdatabase
MCP_CONFIG=list,read,utility
npm install
npm run build
See AI Agent Configuration section below.
Completely restart your AI agent application to load the MCP server.
Try asking your AI:
"What databases are available?" "Show me all tables in my database" "What's the structure of the users table?" "Show me the first 5 records from users"
Most AI agents use a similar JSON configuration format (the file location varies by tool).
The examples below use the default stdio transport, where the AI agent starts the server itself. Remote clients connect over HTTP instead; see Remote Access.
Universal Configuration Template:
Option 1: Single-Layer (Permissions Only) - Simple Setup
{
"mcpServers": {
"mysql": {
"command": "npx",
"type": "stdio",
"args": [
"-y",
"@berthojoris/mcp-mysql-server",
"mysql://user:password@localhost:3306/database",
"list,read,utility,create,update,ddl"
]
}
}
}
Option 2: Dual-Layer (Permissions + Categories) - Recommended for Fine Control
{
"mcpServers": {
"mysql": {
"command": "npx",
"type": "stdio",
"args": [
"-y",
"@berthojoris/mcp-mysql-server",
"mysql://user:password@localhost:3306/database_name_here",
"list,read,utility,create,update,ddl,transaction",
"database_discovery,crud_operations,custom_queries,schema_management,index_management,constraint_management,table_maintenance,query_optimization,analysis,seed_operations"
]
}
}
}
💡 Tip: The dual-layer approach provides granular control. The 4th argument (permissions) controls broad access levels, while the 5th argument (categories) fine-tunes which specific tools are available.
Alternative approach using environment variables instead of connection string:
Option 1: Permissions Only (Simple)
{
"mcpServers": {
"mysql": {
"command": "npx",
"type": "stdio",
"args": ["-y", "@berthojoris/mcp-mysql-server"],
"env": {
"DB_HOST": "localhost",
"DB_PORT": "3306",
"DB_USER": "root",
"DB_PASSWORD": "your_password",
"DB_NAME": "your_database",
"MCP_PERMISSIONS": "list,read,utility,create,update,delete"
}
}
}
}
Option 2: Permissions + Categories (Recommended)
{
"mcpServers": {
"mysql": {
"command": "npx",
"type": "stdio",
"args": ["-y", "@berthojoris/mcp-mysql-server"],
"env": {
"DB_HOST": "localhost",
"DB_PORT": "3306",
"DB_USER": "root",
"DB_PASSWORD": "your_password",
"DB_NAME": "your_database",
"MCP_PERMISSIONS": "list,read,utility,create,update,delete",
"MCP_CATEGORIES": "database_discovery,custom_queries,analysis"
}
}
}
}
More configuration details are in DOCUMENTATIONS.md → Configuration.
If a Cursor MCP wrapper can call tools but cannot send arguments, use the no-argument cursor_execute_request bridge. Create .cursor/mysql-mcp-request.json in the workspace, then call cursor_execute_request:
{
"tool": "execute_ddl",
"arguments": {
"query": "DROP TABLE IF EXISTS spark_processes;"
}
}
For direct SQL, the bridge can infer the right SQL tool:
{
"query": "DROP TABLE IF EXISTS spark_processes;",
"mode": "auto"
}
Set MYSQL_MCP_CURSOR_REQUEST_FILE to override the request file path.
For Codex, Claude Code CLI, Cursor, Droid CLI, and other MCP agents, call list_all_tools first. It returns the live runtime catalog, enabled/disabled status, active permission/category profile, and recommended workflows for schema exploration, safe SELECT queries, CSV exports, transactions, and data changes.
Use export_table_to_csv for table-based exports and export_query_to_csv for SELECT query exports.
stdio stays the default. For remote clients such as ChatGPT connectors / developer mode, you can enable the Streamable HTTP transport with a flag or an environment variable, the same way you set permissions. Remove the flag, or set MCP_TRANSPORT=stdio, to turn it off again.
# Read-only MySQL account + bearer token, bound to localhost
export MCP_HTTP_AUTH=token
export MCP_HTTP_AUTH_TOKENS=$(openssl rand -hex 32) # give this token to your clients
npx -y @berthojoris/mcp-mysql-server mysql://mcp_reader:pass@localhost:3306/app "list,read,utility" --transport=http --port=3000
http://127.0.0.1:3000/mcp, plus GET /health. Publish it over HTTPS with a reverse proxy or tunnel, and set MCP_HTTP_PUBLIC_URL.MCP_HTTP_AUTH=token (bearer tokens) or oauth (OAuth 2.1 JWT validation against your authorization server, with RFC 9728 metadata, as needed by ChatGPT). none only works on loopback.Host/Origin checks (DNS-rebinding protection). Each session is bound to its identity, and each transaction to its session. A session's open transactions are rolled back when it closes or expires.MCP_HTTP_* settings are ignored over stdio.readOnlyHint and destructiveHint.Protections are on by default in HTTP mode and off by default over stdio, so existing stdio setups behave as before. Every value can be overridden with an environment variable on either transport.
In HTTP mode the server runs as a standalone service, so put the settings in .env (or your process manager) instead of an MCP client's command config:
DB_HOST=localhost
DB_USER=mcp_reader
DB_PASSWORD=pass
DB_NAME=app
MCP_PERMISSIONS=list,read,utility
MCP_TRANSPORT=http
MCP_HTTP_PORT=3000
MCP_HTTP_AUTH=token
MCP_HTTP_AUTH_TOKENS=<64-hex-token>
MCP_QUERY_TIMEOUT_MS=15000
MCP_AUDIT_LOG=logs/mcp-audit.log
From the directory that holds .env, start it with node dist/mcp-server.js (from a clone) or the npx command above (a connection string argument overrides the DB_* values). Then point clients that support remote MCP servers at the URL. For example, in Claude Code's .mcp.json:
{
"mcpServers": {
"mysql-remote": {
"type": "http",
"url": "http://127.0.0.1:3000/mcp",
"headers": { "Authorization": "Bearer <64-hex-token>" }
}
}
}
Full details (OAuth setup, sessions, read-only user SQL) are in DOCUMENTATIONS.md → Remote Access.
Control database access with a dual-layer filtering system that provides both broad and fine-grained control:
Filtering Logic: Tool enabled = (Has Permission) AND (Has Category OR No categories specified)
Security changes in v1.46.0 (review before upgrading):
optimize_table, repair_table, flush_table, and optimize_fulltext now require ddl instead of utility, so the read-only default no longer includes them. flush_table is limited to the connected database and no longer accepts with_read_lock.run_select_query drops invalid optimizer hint values and validates the query again after hints are applied.mysql . user).Changes in v1.44.0 (review before upgrading):
list,read,utility (previously every tool). To keep full access, pass list,read,create,update,delete,execute,ddl,utility,transaction,procedure.mysql schema: without a database in the connection string or DB_NAME, database-scoped tools report "No database specified" instead of using the mysql system schema.CACHE_ENABLED=true. Any write and every transaction commit now clears the cache.#, ;, and -- inside string values (e.g. '#fff') are no longer rejected. WITH (CTE) queries are supported and, like derived tables, need execute in read queries.Security changes in v1.43.4:
EXPLAIN ANALYZE runs the statement it wraps (MySQL 8.0.18+), so it now requires that statement's permission: delete for DELETE, update or execute for UPDATE, read for SELECT. Plan-only EXPLAIN still needs just list or read.Security changes in v1.43.3:
utility and read; enable the utilities category when filtering categories.transaction alone does not permit reads or writes.execute_write_query accepts only INSERT/UPDATE/DELETE. DDL requires enabled DDL tools.utility and an enabled destination tool.execute does not bypass mandatory SQL safety restrictions, including file access and account/privilege changes.Report suspected security issues privately via Private Vulnerability Reporting; see SECURITY.md for the policy.
Filtering rules and per-permission details are documented in DOCUMENTATIONS.md → Permission System.
Use documentation categories to fine-tune which tools are exposed (Layer 2):
database_discovery,crud_operations,bulk_operations,seed_operations,custom_queries,schema_management,utilities,transaction_management,stored_procedures,views_management,triggers_management,index_management,constraint_management,table_maintenance,query_optimization,analysis
Tool descriptions per category are in DOCUMENTATIONS.md → Tool Categories.
The server exposes 88 tools organized into categories (CRUD, seed, schema, discovery, and utilities).
readOnlyHint, destructiveHint, idempotentHint); see DOCUMENTATIONS.md → Tool annotationsFor comprehensive documentation, see DOCUMENTATIONS.md:
Remote Access - Streamable HTTP transport, bearer/OAuth authentication, sessions, protection settings, audit log
DDL Operations - Create, alter, and drop tables
Data Export Tools - Export data to CSV format
Relational Data Seeder - Plan, preview, execute, validate, infer rules, and template FK-aware dummy data
Full-Text Search - Create and search FULLTEXT indexes with multiple search modes
Transaction Management - ACID transactions
Stored Procedures - Create and execute with IN/OUT/INOUT parameters
Views & Triggers - Manage database views and triggers
Index & Constraint Management - Optimize performance and enforce data integrity
Table Maintenance - Analyze, optimize, check, and repair tables
Query Logging - See all SQL queries executed automatically
Security Features - Built-in security and best practices
Bulk Operations - High-performance batch processing
Troubleshooting - Common issues and solutions
This MySQL MCP is a powerful intermediary layer between AI assistants and MySQL databases.
For full feature coverage and usage examples, see DOCUMENTATIONS.md.
MIT License - see LICENSE file for details.
Made with care for the AI development community
Enabling AI agents to interact with MySQL databases safely and efficiently
Model Context Protocol server for MySQL database integration with dynamic per-project permissions
{ "mcpServers": { "berthojoris-mcp-mysql-server": { "command": "npx", "args": [ "-y", "@berthojoris/[email protected]" ] } }}Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
@berthojoris/mcp Mysql Server läuft lokal über stdio.
Zuletzt geprüft: 2026-11-16. Model Context Protocol server for MySQL database integration with dynamic per-project permissions