Skip to main content
Glama
designcomputer

MySQL MCP Server

Tests PyPI - Downloads AgentAudit Safe

MySQL MCP Server

A Model Context Protocol (MCP) implementation that enables secure interaction with MySQL databases. This server component facilitates communication between AI applications (hosts/clients) and MySQL databases, making database exploration and analysis safer and more structured through a controlled interface.

Note: MySQL MCP Server supports both standard input/output (STDIO) and Streamable HTTP (SSE) transport modes. The SSE mode is recommended for remote/self-hosted deployments.

Deployment options

  • HostedFronteir AI runs the server for you; no local setup required.

  • LocalSmithery installs and runs the server on your own machine.

Related MCP server: PostgreSQL MCP Server

Features

  • List available MySQL tables as resources

  • Read table contents

  • Execute SQL queries with proper error handling

  • Multi-database mode (Optional MYSQL_DATABASE)

  • SSE/HTTP transport support (MCP_TRANSPORT=sse)

  • SSH Tunneling support

  • Comprehensive schema information

  • Table data sampling

  • Secure database access through environment variables

  • Comprehensive logging

Installation

Manual Installation

pip install mysql-mcp-server

Installing via Smithery

To install MySQL MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install designcomputer/mysql-mcp-server --client claude

Installing via Claude Code CLI

claude mcp add --transport stdio designcomputer-mysql_mcp_server uvx mysql_mcp_server

Installing via Autohand Code CLI

autohand mcp add mysql env MYSQL_HOST=localhost MYSQL_PORT=3306 MYSQL_USER=your_username MYSQL_PASSWORD=your_password MYSQL_DATABASE=your_database uvx mysql_mcp_server

Add --scope project after mcp add to keep the registration in the current workspace. See Autohand Code for current CLI details.

Configuration

Set the following environment variables:

MYSQL_HOST=localhost     # Database host
MYSQL_PORT=3306         # Optional: Database port (defaults to 3306 if not specified)
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database # Optional: Omit for multi-database mode

# Advanced Configuration
MYSQL_SSL_MODE=DISABLED  # DISABLED, REQUIRED, VERIFY_CA, VERIFY_IDENTITY
MYSQL_CONNECT_TIMEOUT=10 # Timeout in seconds

# Connection behaviour (Optional)
MYSQL_SQL_MODE=TRADITIONAL           # SQL mode applied to the connection (default: TRADITIONAL)

# Compatibility (Optional)
MYSQL_CHARSET=utf8mb4
MYSQL_COLLATION=utf8mb4_unicode_ci
MYSQL_AUTH_PLUGIN=       # e.g., mysql_native_password for older MySQL versions
MYSQL_USE_PURE=false     # Force the pure-Python connector (default: false)
MYSQL_RAISE_ON_WARNINGS=false        # Raise on SQL warnings (default: false)

# SSE Transport (Optional)
MCP_TRANSPORT=stdio      # stdio or sse
MCP_SSE_HOST=0.0.0.0     # Listen on all interfaces (required for Docker/hosting)
PORT=8000                # HTTP port (fallback for MCP_SSE_PORT)
MCP_SSE_ALLOWED_HOSTS=   # Comma-separated allowed Host headers (default: localhost:{port},127.0.0.1:{port})

# SSH Tunneling (Optional)
MYSQL_SSH_ENABLE=false   # Set to true to enable
MYSQL_SSH_HOST=          # SSH jump host
MYSQL_SSH_PORT=22        # SSH port
MYSQL_SSH_USER=          # SSH username
MYSQL_SSH_KEY_PATH=      # Path to SSH private key
MYSQL_SSH_REMOTE_HOST=localhost # Host from the perspective of the jump host
MYSQL_SSH_REMOTE_PORT=3306
MYSQL_LOCAL_PORT=3330

.env file loading

On startup the server automatically loads a .env file via python-dotenv, so for local use you can simply:

cp .env.example .env   # then edit with your credentials

The file is read from the process working directory (and parent directories), which works when you run the server yourself from the project folder.

⚠️ Claude Code / Claude Desktop: these hosts launch the server from their own working directory, so the project's .env will not be found and you'll see Missing required database configuration. Put your MYSQL_* values in the env block of the MCP config (shown in the Usage section below) rather than relying on .env.

Multi-Database Mode

When MYSQL_DATABASE is not set, the server operates in multi-database mode:

  • list_resources returns all user databases (system databases are filtered out)

  • Use fully qualified table names like mydb.mytable in SQL queries

  • Note: Only single SQL statements are supported. Multi-statement queries (e.g., USE db; SELECT ...) are not supported.

Available Tools

execute_sql

Executes any standard SQL query.

  • Arguments: query (string)

  • Features: Supports SELECT, SHOW, DESCRIBE, and DML (INSERT, UPDATE, DELETE). DML operations are marked with a destructive hint.

  • Limitation: Single statements only. Multi-statement queries are not supported.

  • Cross-database: Use database.table notation to query any database regardless of the MYSQL_DATABASE setting.

get_schema_info

Provides detailed metadata about database structures.

  • Arguments: table_name (optional string)

  • Output: Column names, types, nullability, default values, and comments.

  • Cross-database: Pass database.table to query a table outside MYSQL_DATABASE; bare names use the configured database.

  • Identifier rules: Names must contain only alphanumeric characters, underscores, and $ (dots are allowed as a separator between database and table names).

get_table_sample

Fetches a representative sample of data.

  • Arguments: table_name (string), limit (optional integer, max 20)

  • Use Case: Quickly understand data formats and content without fetching large result sets.

  • Cross-database: Pass database.table to sample a table outside MYSQL_DATABASE; bare names use the configured database.

  • Identifier rules: Names must contain only alphanumeric characters, underscores, and $ (dots are allowed as a separator between database and table names).

Available Prompts

In addition to tools, the server exposes MCP prompts — guided, multi-step workflows that a client can launch on demand. In Claude Code they appear as slash commands (/mcp__<server>__<prompt>); in Claude Desktop they appear in the prompts (+) menu.

Prompt

Arguments

Description

explore_database

(none)

Systematically explore the database: discover available tables, inspect their schemas, sample the data, and summarize what's there.

analyze_table

table_name (required)

Deep-dive into a specific table: retrieve its schema, sample its data, and suggest useful queries. Accepts database.table notation for cross-database lookups.

Example (Claude Code):

/mcp__mysql__explore_database
/mcp__mysql__analyze_table customers

Both prompts orchestrate the existing get_schema_info and get_table_sample tools; explore_database also uses resource listing to enumerate tables.

Usage

With Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mysql_mcp_server",
        "run",
        "mysql_mcp_server"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

For more detailed examples and agent-specific guidance, see MCP_USECASES.md.

With Visual Studio Code

Add this to your mcp.json:

{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mysql-mcp-server",
        "mysql_mcp_server"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Note: Will need to install uv for this to work

Debugging with MCP Inspector

While MySQL MCP Server isn't intended to be run standalone or directly from the command line with Python, you can use the MCP Inspector to debug it.

The MCP Inspector provides a convenient way to test and debug your MCP implementation:

# Install dependencies
pip install -r requirements.txt
# Use the MCP Inspector for debugging (do not run directly with Python)

The MySQL MCP Server is designed to be integrated with AI applications like Claude Desktop and should not be run directly as a standalone Python program.

Development

# Clone the repository
git clone https://github.com/designcomputer/mysql_mcp_server.git
cd mysql_mcp_server
# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows
# Install development dependencies
pip install -r requirements-dev.txt
# Copy the example config and edit with your credentials
cp .env.example .env
# Edit .env with your MySQL connection details
# Run tests
pytest

Security Considerations

  • Identifier Validation: Table and database names passed to get_schema_info and get_table_sample are validated against a strict whitelist (alphanumeric, underscore, and $ only; a single dot is allowed as a database.table separator). Other special characters are rejected to prevent SQL injection.

  • Encrypted Access: Full support for SSL/TLS and SSH Tunneling for secure remote connections.

  • Log Privacy: Passwords and SSH private keys are automatically masked in server logs.

  • Least Privilege: Always use a dedicated MySQL user with minimal required permissions.

  • SSE transport has no built-in authentication. The SSE server binds to 0.0.0.0 by default and accepts connections without credentials. If you expose it beyond localhost, place it behind a reverse proxy (nginx, Caddy, Traefik) that enforces authentication. Example with nginx and HTTP Basic Auth:

    location /sse {
        auth_basic "MCP";
        auth_basic_user_file /etc/nginx/.htpasswd;
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_buffering off;
    }
    location /messages/ {
        auth_basic "MCP";
        auth_basic_user_file /etc/nginx/.htpasswd;
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
    }

    Set MCP_SSE_HOST=127.0.0.1 so the server only listens on loopback and the proxy is the sole public entry point. Set MCP_SSE_ALLOWED_HOSTS to the public hostname your proxy forwards (e.g. MCP_SSE_ALLOWED_HOSTS=myserver.example.com:443).

See SECURITY.md for a comprehensive guide on securing your deployment.

Security Best Practices

This MCP implementation requires database access to function. For security:

  1. Create a dedicated MySQL user with minimal permissions

  2. Never use root credentials or administrative accounts

  3. Restrict database access to only necessary operations

  4. Enable logging for audit purposes

  5. Regular security reviews of database access

See MySQL Security Configuration Guide for detailed instructions on:

  • Creating a restricted MySQL user

  • Setting appropriate permissions

  • Monitoring database access

  • Security best practices

⚠️ IMPORTANT: Always follow the principle of least privilege when configuring database access.

License

MIT License - see LICENSE file for details.

Contributing

  1. Fork the repository

  2. Create your feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add some amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

Available Tools

3 tools
execute_sqlA
Destructive

Execute a SQL statement against the MySQL server. Use for SELECT, DML (INSERT/UPDATE/DELETE), SHOW, DESCRIBE, and ad-hoc queries. Supports cross-database queries using database.table notation. Single statements only — use fully qualified names instead of USE statements.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesThe SQL statement to execute. Single statements only.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already indicate destructiveHint=true, so the destructive nature is clear. The description adds behavioral info: single statements only, cross-database support, and avoidance of USE statements. This adds value beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, well-structured, and front-loaded with the core action. Every sentence adds value without redundancy. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (SQL execution), the description covers usage guidelines and parameter semantics well. However, it lacks any mention of output format (e.g., rows for SELECT, affected rows for DML) or error handling, which would be helpful since no output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents the 'query' parameter. The description adds practical guidance like using fully qualified names and avoiding USE statements, which enriches understanding beyond the schema's basic description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it executes SQL statements against MySQL server and lists supported statement types (SELECT, DML, SHOW, DESCRIBE, ad-hoc). It distinguishes from USE statements and mentions cross-database queries. However, it doesn't explicitly differentiate from sibling tools like get_schema_info, so a 4 is appropriate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool: for SELECT, DML, SHOW, DESCRIBE, and ad-hoc queries. It also provides guidance to use fully qualified names instead of USE statements and to use single statements only. This gives clear context for appropriate usage, though it doesn't mention when not to use it (e.g., for metadata queries).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_schema_infoA
Read-only

Get column metadata for a table or all tables in the configured database: column names, data types, nullability, default values, and comments. Call this before querying an unfamiliar table. Omit table_name to see all tables at once. Accepts bare table names (uses MYSQL_DATABASE) or database.table for cross-database lookups.

ParametersJSON Schema
NameRequiredDescriptionDefault
table_nameNoOptional: bare table name, or database.table for a cross-database lookup.

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it returns specific metadata and uses MYSQL_DATABASE, which is useful but not extensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences: first states purpose, second gives usage advice, third explains parameter usage. Front-loaded and no superfluous wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only metadata tool with one optional parameter, the description covers what it returns and how to use it. Output schema is absent, but the description lists the metadata fields, which is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a description for the parameter. The description adds valuable context: omitting table_name returns all tables, and bare names use MYSQL_DATABASE. This goes beyond the schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get column metadata for a table or all tables in the configured database' with a specific list of metadata included (column names, data types, etc.). It distinguishes from siblings by implying it's for schema exploration before querying.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises 'Call this before querying an unfamiliar table' and explains optional usage with 'Omit table_name to see all tables at once.' Lacks direct comparison with sibling tools but provides clear context for when to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_table_sampleA
Read-only

Fetch a small sample of rows from a table to understand its data format and content. Use alongside get_schema_info before writing complex queries. Accepts bare table names (uses MYSQL_DATABASE) or database.table for cross-database lookups.

ParametersJSON Schema
NameRequiredDescriptionDefault
table_nameYesTable to sample. Use database.table notation for cross-database queries.
limitNoNumber of rows to return (default 5, max 20).

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark the tool as readOnlyHint=true and destructiveHint=false. The description adds transparency by specifying 'small sample' and the default/max limit behavior, which is valuable beyond annotations. No contradictions detected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, no redundant words. The first sentence front-loads the core purpose; the second adds usage and naming tips. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with two parameters and no output schema, the description covers the essential aspects: what it does, how to use it, and naming conventions. It is complete enough for an AI agent to select and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (both parameters described). The description adds value by explaining that table_name can be bare (using MYSQL_DATABASE) or in database.table format, which goes beyond the schema's description. For limit, the schema already states default and max, so no further addition needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Fetch a small sample'), the resource ('from a table'), and the purpose ('to understand its data format and content'). It distinguishes itself from sibling tools by mentioning alongside get_schema_info and before writing complex queries, implying this tool is for exploration, not execution or schema understanding.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises using the tool alongside get_schema_info before writing complex queries, providing clear context for when to use it. It also explains naming conventions (bare table vs database.table). However, it lacks explicit guidance on when not to use it or comparison to execute_sql for arbitrary queries.

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. Dates show when Glama detected each change.

  1. 3 tool updatesv0.4.1
    • Changedexecute_sql1 field changed
      • changedInput schema / properties / query / description
        Previous value: -"The SQL query to execute"New value: +"The SQL statement to execute. Single statements only."
    • Addedget_schema_info
    • Addedget_table_sample
  2. 1 tool updatev1.0.0
    • First observedexecute_sql

TDQS

A4.3/5.0
Disambiguation5/5

Each tool has a distinct and clear purpose: executing SQL, retrieving schema metadata, and fetching sample data. No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (execute_sql, get_schema_info, get_table_sample), making them predictable.

Tool Count5/5

Three tools is appropriate for the server's scope—covering query execution, schema inspection, and data sampling. Not too few or excessive.

Completeness4/5

Covers core database interaction needs (query, schema, sample). Minor gaps like database listing or DDL support exist but are acceptable for the stated purpose.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    Enables secure interaction with MySQL databases, allowing AI assistants to list tables, read data, and execute SQL queries through a controlled interface.
    -
  • A
    license
    Not graded
    quality
    Not graded
    maintenance
    Provides AI assistants with safe, controlled access to PostgreSQL databases with read-only defaults, granular permissions, query safety features, and schema introspection capabilities.
    1
    -
  • F
    license
    Not graded
    quality
    C
    maintenance
    Enables read-only SQL database access for AI assistants, allowing schema exploration and safe query execution without risk of data modification.
    -
  • A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI assistants to safely query and explore SQL Server and PostgreSQL databases with read-only access, supporting schema discovery, relationship exploration, and query execution.
    37
    3
    MIT

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/designcomputer/mysql_mcp_server'

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