Skip to main content
Glama
neverinfamous

MySQL MCP Server

by neverinfamous
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

mysql-mcp

Last updated January 4, 2026 - Production/Stable v2.1.0

GitHub License: MIT CodeQL Version Status npm version Docker Pulls Security TypeScript Tests Coverage

📚 Full Documentation (Wiki) • Changelog • Security • Release Article

The Most Comprehensive MySQL MCP Server Available

mysql-mcp is the definitive Model Context Protocol server for MySQL — empowering AI assistants like AntiGravity, Claude, Cursor, and other MCP clients with unparalleled database capabilities. Built for developers who demand enterprise-grade features without sacrificing ease of use.

🎯 What Sets Us Apart

Feature

Description

191 Specialized Tools

The largest MySQL tool collection for MCP — from core CRUD and native JSON functions (MySQL 5.7+) to advanced spatial/GIS, document store, and cluster management

18 Observability Resources

Real-time schema, performance metrics, process lists, status variables, replication status, and InnoDB diagnostics

19 AI-Powered Prompts

Guided workflows for query building, schema design, performance tuning, and infrastructure setup

OAuth 2.1 + Access Control

Enterprise-ready security with RFC 9728/8414 compliance, granular scopes (read, write, admin, full, db:*, table:*:*), and Keycloak integration

Smart Tool Filtering

24 tool groups + 7 meta-groups let you stay within IDE limits while exposing exactly what you need

HTTP Streaming Transport

SSE-based streaming with /sse, /messages, and /health endpoints for remote deployments

High-Performance Pooling

Built-in connection pooling for efficient, concurrent database access

Ecosystem Integrations

First-class support for MySQL Router, ProxySQL, and MySQL Shell utilities

Advanced Encryption

Full TLS/SSL support for secure connections, plus tools for managing data masking, encryption monitoring, and compliance

Production-Ready Security

SQL injection protection, parameterized queries, input validation, and audit capabilities

Strict TypeScript

100% type-safe codebase with 1550+ tests and 97% coverage

MCP 2025-11-25 Compliant

Full protocol support with tool safety hints, resource priorities, and progress notifications

🚀 Quick Start

Prerequisites

  • Node.js 18+

  • MySQL 5.7+ or 8.0+ server

  • npm or yarn

Installation

NPM (Recommended)

# Install globally npm install -g @neverinfamous/mysql-mcp # Run mysql-mcp --transport stdio --mysql mysql://user:password@localhost:3306/database # Or use npx without installing npx @neverinfamous/mysql-mcp --transport stdio --mysql mysql://user:password@localhost:3306/database

Docker

docker run -i --rm writenotenow/mysql-mcp:latest \ --transport stdio \ --mysql mysql://user:password@host.docker.internal:3306/database

From Source

git clone https://github.com/neverinfamous/mysql-mcp.git cd mysql-mcp npm install npm run build node dist/cli.js --transport stdio --mysql mysql://user:password@localhost:3306/database

⚡ MCP Client Configuration

HTTP/SSE Server Usage (Advanced)

When to use HTTP mode: Use HTTP mode when deploying mysql-mcp as a standalone server that multiple clients can connect to remotely. For local development with Claude Desktop or Cursor IDE, use the default stdio mode shown below instead.

Use cases for HTTP mode:

  • Running the server in a Docker container accessible over a network

  • Deploying to cloud platforms (AWS, GCP, Azure)

  • Enabling OAuth 2.1 authentication for enterprise security

  • Allowing multiple AI clients to share one database connection

OAuth 2.1 Authentication

For enterprise deployments, mysql-mcp supports OAuth 2.1 authentication with Keycloak or any RFC-compliant provider.

Quick Setup

1. Start with OAuth disabled (default)

mysql-mcp --mysql mysql://root:pass@localhost/db

2. Enable OAuth with an identity provider

mysql-mcp --mysql mysql://root:pass@localhost/db \ --oauth-enabled \ --oauth-issuer http://localhost:8080/realms/mysql-mcp \ --oauth-audience mysql-mcp

Start the HTTP server:

# Local installation node dist/cli.js --transport http --port 3000 --mysql mysql://user:password@localhost:3306/database # Docker (expose port 3000) docker run -p 3000:3000 writenotenow/mysql-mcp \ --transport http \ --port 3000 \ --mysql mysql://user:password@host.docker.internal:3306/database

Available endpoints:

  • GET /sse - Establish MCP connection via Server-Sent Events

  • POST /messages - Send JSON-RPC messages to the server

  • GET /health - Health check endpoint

  • GET /.well-known/oauth-protected-resource - OAuth 2.1 metadata (when OAuth enabled)

💡 Tip: Most users should skip this section and use the stdio configuration below for local AI IDE integration.

Cursor IDE / Claude Desktop

{ "mcpServers": { "mysql-mcp": { "command": "node", "args": [ "C:/path/to/mysql-mcp/dist/cli.js", "--transport", "stdio", "--mysql", "mysql://user:password@localhost:3306/database" ] } } }

Using Environment Variables (Recommended)

{ "mcpServers": { "mysql-mcp": { "command": "node", "args": [ "C:/path/to/mysql-mcp/dist/cli.js", "--transport", "stdio" ], "env": { "MYSQL_HOST": "localhost", "MYSQL_PORT": "3306", "MYSQL_USER": "your_user", "MYSQL_PASSWORD": "your_password", "MYSQL_DATABASE": "your_database" } } } }

📖 See the for more configuration options.

🔗 Database Connection Scenarios

Scenario

Host to Use

Example Connection String

MySQL on host machine

host.docker.internal

mysql://user:pass@host.docker.internal:3306/db

MySQL in Docker

Container name or network

mysql://user:pass@mysql-container:3306/db

Remote/Cloud MySQL

Hostname or IP

mysql://user:pass@db.example.com:3306/db

MySQL on Host Machine

If MySQL is installed directly on your computer (via installer, Homebrew, etc.):

"--mysql", "mysql://user:password@host.docker.internal:3306/database"

MySQL in Another Docker Container

Add both containers to the same Docker network, then use the container name:

# Create network and run MySQL docker network create mynet docker run -d --name mysql-db --network mynet -e MYSQL_ROOT_PASSWORD=pass mysql:8 # Run MCP server on same network docker run -i --rm --network mynet writenotenow/mysql-mcp:latest \ --transport stdio --mysql mysql://root:pass@mysql-db:3306/mysql

Remote/Cloud MySQL (RDS, Cloud SQL, etc.)

Use the remote hostname directly:

"--mysql", "mysql://user:password@your-instance.region.rds.amazonaws.com:3306/database"

Provider

Example Hostname

AWS RDS

your-instance.xxxx.us-east-1.rds.amazonaws.com

Google Cloud SQL

project:region:instance (via Cloud SQL Proxy)

Azure MySQL

your-server.mysql.database.azure.com

PlanetScale

aws.connect.psdb.cloud (SSL required)

DigitalOcean

your-cluster-do-user-xxx.db.ondigitalocean.com

Tip: For remote connections, ensure your MySQL server allows connections from Docker's IP range and that firewalls/security groups permit port 3306.

🛠️ Tool Filtering

IMPORTANT

AI IDEs like Cursor have tool limits (typically 40-50 tools). With 191 tools available, you MUST use tool filtering to stay within your IDE's limits. We recommend starter (38 tools) as a starting point.

What Can You Filter?

The --tool-filter argument accepts shortcuts, groups, or tool names — mix and match freely:

Filter Pattern

Example

Tools

Description

Shortcut only

starter

38

Use a predefined bundle

Groups only

core,json,transactions

32

Combine individual groups

Shortcut + Group

starter,spatial

50

Extend a shortcut

Shortcut - Tool

starter,-mysql_drop_table

37

Remove specific tools

Shortcuts (Predefined Bundles)

Shortcut

Tools

Use Case

What's Included

starter

38

🌟 Recommended

Core, JSON, trans, text

essential

15

Minimal footprint

Core, trans

dev-power

45

Power Developer

Core, schema, perf, stats, fulltext, trans

ai-data

44

AI Data Analyst

Core, JSON, docstore, text, fulltext

ai-spatial

43

AI Spatial Analyst

Core, spatial, stats, perf, trans

dba-monitor

35

DBA Monitoring

Core, monitor, perf, sysschema, opt

dba-manage

33

DBA Management

Core, admin, backup, repl, parts, events

dba-secure

42

DBA Security

Core, security, roles, cluster, trans

base-core

48

Base Ops

Core, JSON, trans, text, schema

base-advanced

39

Advanced Features

DocStore, spatial, stats, fulltext, events

ecosystem

31

External Tools

Router, ProxySQL, Shell

Tool Groups (24 Available)

Group

Tools

Description

core

8

Read/write queries, tables, indexes

transactions

7

BEGIN, COMMIT, ROLLBACK, savepoints

json

17

JSON functions, merge, diff, stats

text

6

REGEXP, LIKE, SOUNDEX

fulltext

4

Natural language search

performance

8

EXPLAIN, query analysis, slow queries

optimization

4

Index hints, recommendations

admin

6

OPTIMIZE, ANALYZE, CHECK

monitoring

7

PROCESSLIST, status variables

backup

4

Export, import, mysqldump

replication

5

Master/slave, binlog

partitioning

4

Partition management

router

9

MySQL Router REST API

proxysql

12

ProxySQL management

shell

10

MySQL Shell utilities

schema

10

Views, procedures, triggers, constraints

events

6

Event Scheduler management

sysschema

8

sys schema diagnostics

stats

8

Statistical analysis tools

spatial

12

Spatial/GIS operations

security

9

Audit, SSL, encryption, masking

cluster

10

Group Replication, InnoDB Cluster

roles

8

MySQL 8.0 role management

docstore

9

Document Store collections

Quick Start: Recommended IDE Configuration

Add one of these configurations to your IDE's MCP settings file (e.g., cline_mcp_settings.json, .cursorrules, or equivalent):

Option 1: Starter (38 Essential Tools)

Best for: General MySQL database work - CRUD operations, schema management, and monitoring.

{ "mcpServers": { "mysql-mcp": { "command": "node", "args": [ "/path/to/mysql-mcp/dist/cli.js", "--transport", "stdio", "--tool-filter", "starter" ], "env": { "MYSQL_HOST": "localhost", "MYSQL_PORT": "3306", "MYSQL_USER": "your_username", "MYSQL_PASSWORD": "your_password", "MYSQL_DATABASE": "your_database" } } } }

Option 2: Cluster (10 Tools for InnoDB Cluster Monitoring)

Best for: Monitoring InnoDB Cluster, Group Replication status, and cluster topology.

⚠️ Prerequisites:

  • InnoDB Cluster must be configured and running with Group Replication enabled

  • Connect to a cluster node directly (e.g., localhost:3307) — NOT a standalone MySQL instance

  • Use cluster_admin or root user with appropriate privileges

  • See MySQL Ecosystem Setup Guide for cluster setup instructions

{ "mcpServers": { "mysql-mcp-cluster": { "command": "node", "args": [ "/path/to/mysql-mcp/dist/cli.js", "--transport", "stdio", "--tool-filter", "cluster" ], "env": { "MYSQL_HOST": "localhost", "MYSQL_PORT": "3307", "MYSQL_USER": "cluster_admin", "MYSQL_PASSWORD": "cluster_password", "MYSQL_DATABASE": "mysql" } } } }

Option 3: Ecosystem (31 Tools for InnoDB Cluster Deployments)

Best for: MySQL Router, ProxySQL, MySQL Shell, and InnoDB Cluster deployments.

⚠️ Prerequisites:

  • InnoDB Cluster with MySQL Router requires the cluster to be running for Router REST API authentication (uses metadata_cache backend)

  • Router REST API uses HTTPS with self-signed certificates by default — set MYSQL_ROUTER_INSECURE=true to bypass certificate verification

  • See MySQL Ecosystem Setup Guide for detailed instructions

{ "mcpServers": { "mysql-mcp-ecosystem": { "command": "node", "args": [ "/path/to/mysql-mcp/dist/cli.js", "--transport", "stdio", "--tool-filter", "ecosystem" ], "env": { "MYSQL_HOST": "localhost", "MYSQL_PORT": "3307", "MYSQL_USER": "cluster_admin", "MYSQL_PASSWORD": "cluster_password", "MYSQL_DATABASE": "mysql", "MYSQL_ROUTER_URL": "https://localhost:8443", "MYSQL_ROUTER_USER": "rest_api", "MYSQL_ROUTER_PASSWORD": "router_password", "MYSQL_ROUTER_INSECURE": "true", "PROXYSQL_HOST": "localhost", "PROXYSQL_PORT": "6032", "PROXYSQL_USER": "radmin", "PROXYSQL_PASSWORD": "radmin", "MYSQLSH_PATH": "/usr/local/bin/mysqlsh" } } } }

Customization Notes:

  • Replace /path/to/mysql-mcp/ with your actual installation path

  • Update credentials with your actual values

  • For Windows: Use forward slashes (e.g., C:/mysql-mcp/dist/cli.js) or escape backslashes

  • For Windows MySQL Shell: "MYSQLSH_PATH": "C:\\Program Files\\MySQL\\MySQL Shell 9.5\\bin\\mysqlsh.exe"

  • Router Authentication: Router REST API authenticates against the InnoDB Cluster metadata. The cluster must be running for authentication to work.

  • Cluster Resource: The mysql://cluster resource is only available when connected to an InnoDB Cluster node

Legacy Syntax (still supported): If you start with a negative filter (e.g., -ecosystem), it assumes you want to start with all tools enabled and then subtract.

Syntax Reference

Prefix

Target

Example

Effect

(none)

Shortcut

starter

Whitelist Mode: Enable ONLY this shortcut

(none)

Group

core

Whitelist Mode: Enable ONLY this group

+

Group

+spatial

Add tools from this group to current set

-

Group

-admin

Remove tools in this group from current set

+

Tool

+mysql_explain

Add one specific tool

-

Tool

-mysql_drop_table

Remove one specific tool

📖 See the for advanced examples.

💡 Usage Instructions

NOTE

Usage instructions areautomatically provided to AI agents via the MCP protocol during server initialization.

For debugging or manual reference, see the source: src/constants/ServerInstructions.ts

🤖 AI-Powered Prompts

This server includes 19 intelligent prompts for guided workflows:

Prompt

Description

mysql_query_builder

Construct SQL queries with security best practices

mysql_schema_design

Design table schemas with indexes and relationships

mysql_performance_analysis

Analyze slow queries with optimization recommendations

mysql_migration

Generate migration scripts with rollback options

mysql_database_health_check

Comprehensive database health assessment

mysql_backup_strategy

Enterprise backup planning with RTO/RPO

mysql_index_tuning

Index analysis and optimization workflow

mysql_setup_router

MySQL Router configuration guide

mysql_setup_proxysql

ProxySQL configuration guide

mysql_setup_replication

Replication setup guide

mysql_setup_shell

MySQL Shell usage guide

mysql_tool_index

Complete tool index with categories

mysql_quick_query

Quick query execution shortcut

mysql_quick_schema

Quick schema exploration

mysql_setup_events

Event Scheduler setup guide

mysql_sys_schema_guide

sys schema usage and diagnostics

mysql_setup_spatial

Spatial/GIS data setup guide

mysql_setup_cluster

InnoDB Cluster/Group Replication guide

mysql_setup_docstore

Document Store / X DevAPI guide

📊 Resources

This server exposes 18 resources for database observability:

Resource

Description

mysql://schema

Full database schema

mysql://tables

Table listing with metadata

mysql://variables

Server configuration variables

mysql://status

Server status metrics

mysql://processlist

Active connections and queries

mysql://pool

Connection pool statistics

mysql://capabilities

Server version, features, tool categories

mysql://health

Comprehensive health status

mysql://performance

Query performance metrics

mysql://indexes

Index usage and statistics

mysql://replication

Replication status and lag

mysql://innodb

InnoDB buffer pool and engine metrics

mysql://events

Event Scheduler status and scheduled events

mysql://sysschema

sys schema diagnostics summary

mysql://locks

InnoDB lock contention detection

mysql://cluster

Group Replication/InnoDB Cluster status

mysql://spatial

Spatial columns and indexes

mysql://docstore

Document Store collections

🔧 Advanced Configuration

For specialized setups, see these Wiki pages:

Topic

Description

MySQL Router

Configure Router REST API access for InnoDB Cluster

ProxySQL

Configure ProxySQL admin interface access

MySQL Shell

Configure MySQL Shell for dump/load operations

⚡ Performance Tuning

Variable

Default

Description

METADATA_CACHE_TTL_MS

30000

Cache TTL for schema metadata (milliseconds)

LOG_LEVEL

info

Log verbosity: debug, info, warning, error

Tip: Lower METADATA_CACHE_TTL_MS for development (e.g., 5000), or increase it for production with stable schemas (e.g., 300000 = 5 min).

CLI Options

Option

Environment Variable

Description

--oauth-enabled

OAUTH_ENABLED

Enable OAuth authentication

--oauth-issuer

OAUTH_ISSUER

Authorization server URL

--oauth-audience

OAUTH_AUDIENCE

Expected token audience

--oauth-jwks-uri

OAUTH_JWKS_URI

JWKS URI (auto-discovered)

--oauth-clock-tolerance

OAUTH_CLOCK_TOLERANCE

Clock tolerance in seconds

Scopes

Scope

Access Level

read

Read-only queries

write

Read + write operations

admin

Administrative operations

full

All operations

📖 See the for Keycloak setup and detailed configuration.

Development

MCP Inspector

Use MCP Inspector to visually test and debug mysql-mcp:

# Build the server first npm run build # Launch Inspector with mysql-mcp npx @modelcontextprotocol/inspector node dist/cli.js \ --transport stdio \ --mysql mysql://user:password@localhost:3306/database

Open http://localhost:6274 to browse all 191 tools, 18 resources, and 19 prompts interactively.

CLI mode for scripting:

# List all tools npx @modelcontextprotocol/inspector --cli node dist/cli.js \ --transport stdio --mysql mysql://... \ --method tools/list # Call a specific tool npx @modelcontextprotocol/inspector --cli node dist/cli.js \ --transport stdio --mysql mysql://... \ --method tools/call --tool-name mysql_list_tables

📖 See the for detailed usage.

Unit Testing

The project maintains high test coverage (~97%) using Vitest.

# Run tests npm test # Run coverage report npm run test:coverage

Test Infrastructure:

  • Centralized mock factories in src/__tests__/mocks/

  • All 101 test files use shared mocks for consistency

  • Tests run without database connection (fully mocked)

  • ~53 second total runtime

Test Coverage:

Component

Coverage

Notes

Global

97%+

Statement coverage

MySQLAdapter

93%+

Adapter logic covered

Branch Coverage

~86%

High branch coverage

Tools (All)

99%+

1590 tests passing

Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting a pull request.

Security

For security concerns, please see our Security Policy.

⚠️ Never commit credentials - Store secrets in .env (gitignored)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Code of Conduct

Please read our Code of Conduct before participating in this project.

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/neverinfamous/mysql-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server