Skip to main content
Glama
ImRieul

MySQL MCP Server

by ImRieul

@imrieul/mysql-mcp-server

한국어 | 日本語 | 中文 | Español | Português | Français | Русский

A simple MySQL MCP server.

Features

  • LLM-friendly — compact column/row format, auto LIMIT, error hints with next-action suggestions

  • Bulk schemadescribe_all_tables returns entire DB schema in one call

  • Read-only mode — app-level prefix check + DB-level SET SESSION TRANSACTION READ ONLY

  • Query timeoutPromise.race() based timeout with guaranteed connection cleanup

  • SSL support — one env var to enable encrypted connections

  • Minimal — 3 dependencies, zero config required

Related MCP server: tokenlite-mysql-mcp

Quick Start

Add to your MCP config (.mcp.json or claude_desktop_config.json):

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@imrieul/mysql-mcp-server"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your-password",
        "MYSQL_DATABASE": "your-database"
      }
    }
  }
}

Or with a connection string:

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@imrieul/mysql-mcp-server", "mysql://root:password@localhost:3306/mydb"]
    }
  }
}

Codex

Codex uses TOML config, not mcpServers JSON. Add this to ~/.codex/config.toml or a project-scoped .codex/config.toml:

[mcp_servers.mysql]
command = "npx"
args = ["-y", "@imrieul/mysql-mcp-server"]

[mcp_servers.mysql.env]
MYSQL_HOST = "localhost"
MYSQL_PORT = "3306"
MYSQL_USER = "root"
MYSQL_PASSWORD = "your-password"
MYSQL_DATABASE = "your-database"

opencode

Add this to opencode.json or opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mysql": {
      "type": "local",
      "command": ["npx", "-y", "@imrieul/mysql-mcp-server"],
      "enabled": true,
      "environment": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your-password",
        "MYSQL_DATABASE": "your-database"
      }
    }
  }
}

Read-only mode with SSL

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@imrieul/mysql-mcp-server", "--readonly"],
      "env": {
        "MYSQL_HOST": "db.example.com",
        "MYSQL_USER": "readonly_user",
        "MYSQL_PASSWORD": "password",
        "MYSQL_DATABASE": "production",
        "MYSQL_SSL": "true",
        "MYSQL_QUERY_TIMEOUT": "10000"
      }
    }
  }
}

Tools

Tool

Description

Read-only mode

query

Execute SELECT, SHOW, DESCRIBE, EXPLAIN

Allowed

execute

Execute INSERT, UPDATE, DELETE, DDL

Blocked

list_databases

List all databases

Allowed

list_tables

List tables in a database

Allowed

describe_table

Show table schema

Allowed

describe_all_tables

Show all table schemas at once

Allowed

Configuration

Environment variables

Variable

Required

Default

Description

MYSQL_HOST

Yes

MySQL host

MYSQL_USER

Yes

MySQL user

MYSQL_PASSWORD

Yes

MySQL password

MYSQL_PORT

No

3306

MySQL port

MYSQL_DATABASE

No

Default database

MYSQL_READONLY

No

false

Read-only mode

MYSQL_MAX_ROWS

No

100

Auto LIMIT for SELECT queries

MYSQL_QUERY_TIMEOUT

No

30000

Query timeout in ms (0 to disable)

MYSQL_SSL

No

false

Enable SSL connection

Connection string

mysql://user:password@host:port/database

Passed as the first CLI argument. Takes priority over environment variables.

License

MIT

Available Tools

7 tools
add_commentA

Safely add a comment to a table or column. This tool only modifies comments — it cannot alter table structure, column types, or data. Set dryRun=true to preview the generated SQL without executing it. Use describe_table first to verify column names. Not available in read-only mode.

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYesTable name.
columnNoColumn name. If omitted, sets a table-level comment.
commentYesComment text to set.
databaseNoDatabase name. Uses the current database if omitted.
dryRunNoIf true, returns the generated SQL without executing it. Defaults to false.

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations, the description carries full burden. It discloses safety, modification scope, preview capability, and read-only restriction. Could add detail on persistence (e.g., commits immediately) but sufficient.

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?

Four sentences, no redundancy, front-loaded with purpose. Every sentence serves a distinct function: purpose, constraints, usage tip, prerequisite, mode restriction.

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 full schema coverage, the description covers safety, prerequisites, preview mode, and read-only restriction. No gaps given the tool's complexity.

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

Parameters3/5

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

Schema coverage is 100% and already explains each parameter. The description adds no new semantic value beyond what the schema descriptions provide, meeting baseline but not exceeding.

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 that the tool adds comments to tables or columns, distinguishes its limited scope (cannot alter structure or data) from sibling tools like execute and query, and specifies the safety aspect.

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?

Provides explicit usage guidance: use describe_table first to verify column names, set dryRun=true for preview, and notes unavailability in read-only mode. Lacks explicit comparison to alternatives but covers key use cases.

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

describe_all_tablesA

Show the schema of all tables at once. Much more efficient than calling describe_table for each table individually. Warning: response can be large for databases with many tables — prefer describe_table for specific tables when possible.

ParametersJSON Schema
NameRequiredDescriptionDefault
databaseNoDatabase name. Uses the current database if omitted.

TDQS

A4.2/5.0
Behavior3/5

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

No annotations provided, so description carries full burden. Warns about large response size but does not mention permissions, side effects, or output format. Adequate but 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.

Conciseness5/5

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

Two sentences plus a warning, every sentence adds value, front-loaded with purpose. Highly concise and structured.

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 simple tool with one optional parameter and no output schema, the description covers purpose, efficiency comparison, and size warning. Could optionally describe response structure, but largely complete.

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

Parameters3/5

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

Schema description coverage is 100%, and description adds no new parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.

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?

Clearly states 'Show the schema of all tables at once' with specific verb and resource, explicitly distinguishes from sibling tool 'describe_table'.

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

Usage Guidelines5/5

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

Explicitly recommends using describe_table for specific tables when efficient, and warns about large responses, providing clear when-to-use and when-not-to-use guidance.

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

describe_tableA

Show the schema/structure of a table, including column names, types, constraints, and comments. Use this before writing queries to ensure correct column names and types. For inspecting all tables at once, use describe_all_tables instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYesTable name to describe.
databaseNoDatabase name. Uses the current database if omitted.

TDQS

A4.2/5.0
Behavior3/5

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

With no annotations, the description must carry behavioral disclosure. It indicates the tool shows schema/structure without side effects, but lacks details on error handling (e.g., if table doesn't exist), authorization needs, or whether it's read-only. Adequate but 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.

Conciseness5/5

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

Two sentences: first explains purpose, second adds usage guidance and sibling reference. No redundant information; every sentence is valuable.

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 simple schema inspection tool with 2 params, the description covers purpose, usage, and differentiation. However, it omits mention of output format or error behavior. No output schema exists, so description could hint at return structure.

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

Parameters3/5

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

Schema description coverage is 100%, with both parameters well-described. The description does not add additional semantic meaning beyond what's in the schema, so baseline 3 is appropriate.

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 starts with 'Show the schema/structure of a table, including column names, types, constraints, and comments,' clearly identifying the verb and resource. It specifies the output content and distinguishes itself from the sibling tool 'describe_all_tables'.

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

Usage Guidelines5/5

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

Explicitly states when to use: 'Use this before writing queries to ensure correct column names and types.' Also says to use 'describe_all_tables' instead for inspecting all tables, providing a clear alternative.

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

executeA

Execute a data modification SQL statement (INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, etc.). Set dryRun=true to validate without executing — uses EXPLAIN for DML, or previews the SQL for DDL. Always confirm destructive operations (DROP, TRUNCATE, DELETE without WHERE) with the user before executing. Not available in read-only mode.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesThe SQL statement to execute. SELECT statements are not allowed here; use the "query" tool instead.
dryRunNoIf true, validates the statement via EXPLAIN without executing it. Defaults to false.

TDQS

A4.9/5.0
Behavior5/5

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

With no annotations, the description fully discloses behavioral traits: it executes modifications, dryRun uses EXPLAIN for DML/previews for DDL, requires user confirmation for destructive ops, and is restricted in read-only mode.

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 concise sentences, front-loaded with purpose. Each sentence adds necessary context without redundancy.

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?

Given the tool's complexity and safety implications, the description covers purpose, usage, validation, and restrictions. While no output schema exists, the behavior is adequately described for an agent.

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% (baseline 3). The description adds value by explaining dryRun's behavior (EXPLAIN for DML, preview for DDL) and reinforcing that sql is for modification statements, not SELECT.

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 it executes data modification SQL statements (INSERT, UPDATE, DELETE, etc.) and explicitly distinguishes from the 'query' tool by excluding SELECT. It names specific SQL verbs, providing a precise scope.

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

Usage Guidelines5/5

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

It provides when to use (data modification SQL), when not to use (SELECT, use query instead), and includes safety guidelines: dryRun for validation, confirmation for destructive operations, and unavailability in read-only mode.

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

list_databasesA

List all databases on the MySQL server. Use this as a starting point to discover available databases before querying. Returns a JSON array of database names.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

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

Discloses basic behavior (lists all databases) and return format, but omits potential permissions or limitations. With no annotations, description carries full burden, so 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.

Conciseness5/5

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

Two concise sentences, first states purpose, second adds usage context. No filler, front-loaded.

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?

Complete for a simple tool: explains purpose and output format. Could mention ordering or permissions, but not necessary.

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

Parameters3/5

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

No parameters exist; schema coverage is 100% trivially. Baseline 3 applies as 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.

Purpose5/5

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

Clear verb 'List' and resource 'all databases on MySQL server', specifies return format 'JSON array of database names', and distinguishes from sibling tools focused on tables and queries.

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?

Provides explicit usage context: 'Use this as a starting point to discover available databases before querying.' Lacks exclusion or alternative guidance, but adequate given no similar siblings.

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

list_tablesA

List all tables in the specified database (or the current database if not specified). Includes table comments when available. Use this before describe_table to find the exact table name.

ParametersJSON Schema
NameRequiredDescriptionDefault
databaseNoDatabase name. Uses the current database if omitted.

TDQS

A4.2/5.0
Behavior4/5

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

No annotations provided, but the description adequately discloses the read-only nature and includes comments. It does not mention permissions or performance, but for a simple listing tool, this is sufficient.

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?

Two sentences, both valuable: purpose and usage guidance. No unnecessary words, effectively front-loaded.

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 simple list tool, the description covers purpose, optional parameter, and usage context. Return format is not described, but the sibling tools imply minimal needed detail.

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

Parameters3/5

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

Schema coverage is 100% and the description repeats the schema's parameter description. No additional meaning is added beyond what the schema provides, so baseline score of 3 is appropriate.

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 lists tables with optional database specification and includes comments. It distinguishes from siblings like describe_table and list_databases.

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 recommends using this before describe_table, providing clear context. It could further exclude cases when not to use it, but the guidance is specific and helpful.

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

queryA

Execute a read-only SQL query (SELECT, SHOW, DESCRIBE, EXPLAIN). LIMIT is auto-appended to SELECT/WITH queries without one (default: server maxRows). Prefer specific columns over SELECT * to reduce response size. For data modification, use the "execute" tool instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesThe SQL query to execute. Only SELECT, SHOW, DESCRIBE, EXPLAIN, and WITH (CTE) statements are allowed.

TDQS

A4.7/5.0
Behavior4/5

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

Discloses auto-appended LIMIT for SELECT/WITH queries and mentions the read-only nature. No annotations are provided, but the description adds significant behavioral context without contradictions.

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, each serving a purpose: stating function, explaining auto-limit, and providing usage guidance. No redundant words.

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 single-parameter SQL query tool without output schema, the description covers purpose, allowed operations, automatic behavior, best practice, and alternative tool, making it fully informative.

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 covers 100% of the parameter, but the description adds guidance on allowed statement types and query best practices, enhancing the schema's basic 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?

Clearly states the tool executes read-only SQL queries, listing specific statement types (SELECT, SHOW, DESCRIBE, EXPLAIN) and distinguishes itself from the sibling 'execute' tool for data modification.

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

Usage Guidelines5/5

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

Explicitly states when to use (read-only queries) and when not (data modification), and provides a best practice to prefer specific columns over SELECT * to reduce response size.

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

TDQS

A4.4/5.0
Disambiguation5/5

All tools have clearly distinct purposes: listing databases, listing tables, describing schemas (single or all), querying read-only, executing modifications, and adding comments. No overlap or confusion.

Naming Consistency5/5

All tool names use a consistent verb_noun pattern in snake_case (e.g., list_databases, describe_table), with clear verbs like add, describe, execute, list, query. The naming is uniform and predictable.

Tool Count5/5

With 7 tools, the server is well-scoped for MySQL database interactions. Each tool addresses a core operation without redundancy, and the count is appropriate for the domain.

Completeness5/5

The tool set covers the full lifecycle: discovery (list databases/tables), schema inspection (describe), data querying (query), modifications (execute), and metadata updates (add_comment). The execute tool handles any SQL needed, so there are no gaps.

Maintenance

ActivityInactive
ResponsivenessSyncing

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

  • GibsonAI MCP server: manage your databases with natural language

  • The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.

  • The Instant MCP server is a wrapper around the Instant Platform SDK that enables creating, managing, and updating InstantDB applications directly within an editor. It provides tools for fetching rules files for LLMs, retrieving and pushing app schemas, managing permission rules, and executing database queries. Key capabilities include schema management (get-schema, push-schema), permission management (get-perms, push-perms), query execution, and listing recent query history.

  • MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.

Related MCP Servers

  • A
    license
    A
    quality
    C
    maintenance
    Secure and token-efficient MySQL MCP server built specifically for AI agents. Prevents hallucinations, optimizes context windows and blocks dangerous queries.
    5
    89
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    A secure and efficient MCP server for MySQL database operations, enabling LLMs to execute SQL queries with read-only access by default and optional write permissions.
    3
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    A multi-database MCP server that enables LLMs to safely interact with MySQL, PostgreSQL, SQLite, and others through a unified tool interface, with permission modes and schema resources.
    16
    66
    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/ImRieul/mysql-mcp-server'

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