Skip to main content
Glama
MySQL MCP Server

MySQL MCP Server

by hovecapital

MySQL MCP Server

MCP Registry npm version

A Model Context Protocol (MCP) server that enables Claude Desktop to interact with MySQL databases through natural language queries.

Features

  • Execute read-only SQL queries through Claude Desktop

  • Dynamic connection configuration — connect to any MySQL database at runtime via connection string

  • Built-in security with query validation (SELECT, WITH, SHOW, DESCRIBE and EXPLAIN only, one statement, no comments) plus a server-side read-only transaction

  • Easy integration with Claude Desktop

  • JSON formatted query results

  • Environment-based configuration for database credentials

Related MCP server: MCP MySQL Server

Quick Start

claude mcp add mysql -s user -- npx -y @hovecapital/read-only-mysql-mcp-server@latest

Then set your database environment variables:

export DB_HOST=localhost
export DB_PORT=3306
export DB_DATABASE=your_database_name
export DB_USERNAME=your_username
export DB_PASSWORD=your_password

Done! Restart Claude Code and ask: "What tables are in my database?"

For Claude Desktop Users (Manual Configuration)

1. Open your config file:

# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json

2. Add this configuration:

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@hovecapital/read-only-mysql-mcp-server@latest"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

3. Save, restart Claude Desktop, and test!

Prerequisites

  • Node.js (v16 or higher) - If using mise, update the command path accordingly

  • MySQL database server

  • Claude Desktop application

Installation

This server is published in the Model Context Protocol Registry as capital.hove/read-only-local-mysql-mcp-server.

Method A: Claude Code CLI (Easiest!)

claude mcp add mysql -s user -- npx -y @hovecapital/read-only-mysql-mcp-server@latest

Then configure your database credentials using environment variables. Restart Claude Code and you're done!

Benefits:

  • One command installation

  • No manual JSON editing

  • Automatic configuration

Method B: Manual JSON Configuration

For Claude Desktop:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@hovecapital/read-only-mysql-mcp-server@latest"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

For Claude Code:

Edit ~/.config/claude-code/settings.json (macOS/Linux) or %APPDATA%\claude-code\settings.json (Windows):

{
  "mcp": {
    "servers": {
      "mysql": {
        "command": "npx",
        "args": ["-y", "@hovecapital/read-only-mysql-mcp-server@latest"],
        "env": {
          "DB_HOST": "localhost",
          "DB_PORT": "3306",
          "DB_DATABASE": "your_database_name",
          "DB_USERNAME": "your_username",
          "DB_PASSWORD": "your_password"
        }
      }
    }
  }
}

Option 2: Install from npm

npm install -g @hovecapital/read-only-mysql-mcp-server

Option 3: Installation with Claude Code

If you're using Claude Code, you can easily install this MCP server:

# Clone the repository
git clone https://github.com/hovecapital/read-only-local-mysql-mcp-server.git
cd read-only-local-mysql-mcp-server

# Install dependencies and build
npm install
npm run build

Then configure Claude Code by adding to your MCP settings.

Option 4: Manual Installation

1. Clone or Download

Save the repository to a directory on your system:

mkdir ~/mcp-servers/mysql
cd ~/mcp-servers/mysql
git clone https://github.com/hovecapital/read-only-local-mysql-mcp-server.git .

2. Install Dependencies

npm install
npm run build

Configuration

Note: If you installed via Option 1 (MCP Registry with npx), you've already configured everything! This section is for users who chose Options 2, 3, or 4 (npm or manual installation).

Claude Code Configuration

If you're using Claude Code with a manual installation, add the MySQL server to your MCP settings:

  1. Open your Claude Code settings (typically in ~/.config/claude-code/settings.json on macOS/Linux or %APPDATA%\claude-code\settings.json on Windows)

  2. Add the MySQL MCP server configuration:

{
  "mcp": {
    "servers": {
      "mysql": {
        "command": "node",
        "args": ["/absolute/path/to/read-only-local-mysql-mcp-server/dist/index.js"],
        "env": {
          "DB_HOST": "localhost",
          "DB_PORT": "3306",
          "DB_DATABASE": "your_database_name",
          "DB_USERNAME": "your_username",
          "DB_PASSWORD": "your_password"
        }
      }
    }
  }
}
  1. Restart Claude Code for the changes to take effect.

Claude Desktop Configuration

If you're using Claude Desktop with a manual installation, open your Claude Desktop configuration file:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Add the MySQL server configuration:

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["/absolute/path/to/read-only-local-mysql-mcp-server/dist/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

Using mise for Node.js

If you're using mise for Node.js version management, make sure to use the full path to the Node.js executable in your configuration.

Environment Variables

Variable

Description

Default

DB_HOST

MySQL server hostname

mysql

DB_PORT

MySQL server port

3306

DB_DATABASE

Database name

database

DB_USERNAME

MySQL username

root

DB_PASSWORD

MySQL password

(empty)

DB_ALLOWED_HOSTS

Comma-separated extra hosts a connection string may point at. DB_HOST and loopback are always allowed.

(empty)

Usage

  1. Restart Claude Desktop after updating the configuration

  2. Start chatting with Claude about your database

Example Queries

"Show me all tables in my database"
"What's the structure of the users table?"
"Get the first 10 records from the products table"
"How many orders were placed last month?"
"Show me users with email addresses ending in @gmail.com"

Claude will automatically convert your natural language requests into appropriate SQL queries and execute them against your database.

Tools

connect

Connect to a MySQL database using a connection string. The connection persists for subsequent queries until changed or disconnected.

Parameters:

Parameter

Required

Description

connectionString

Yes

MySQL connection string (e.g., mysql://user:password@host:port/database)

disconnect

Disconnect from the current runtime database and revert to the default environment-configured connection. Takes no parameters.

query

Run a read-only SQL query against the currently connected database.

Parameters:

Parameter

Required

Description

sql

Yes

SQL query to execute (read-only)

connectionString

No

MySQL connection string to override the current connection for this query only

Dynamic Connection

The server supports switching databases at runtime without restarting. Connection priority:

  1. Per-query connectionString — overrides everything for a single query

  2. Runtime connection (from connect tool) — persists until disconnect is called

  3. Environment variables — the default fallback

Connection string format:

mysql://username:password@hostname:port/database_name

The hostname must be DB_HOST, a loopback address, or listed in DB_ALLOWED_HOSTS. Any other host is rejected before a connection is attempted, so the tools cannot be used to probe the network. Connection failures return a generic message and the real error is written to stderr.

Example workflow:

1. connect → mysql://analyst:pass@prod-db:3306/analytics
2. query   → SELECT COUNT(*) FROM events
3. query   → SELECT * FROM users LIMIT 5 (uses the same analytics connection)
4. query   → SELECT * FROM orders LIMIT 5, connectionString: mysql://analyst:pass@prod-db:3306/sales
              (one-off override — does not change the stored connection)
5. disconnect → reverts to env var defaults

Security Features

Read-Only Operations

Queries are checked in two layers:

  1. Query validation — the statement must start with SELECT, WITH, SHOW, DESCRIBE or EXPLAIN, contain a single statement, contain no comments, and must not contain state-changing keywords anywhere (for example UPDATE, DELETE, INTO OUTFILE, INTO DUMPFILE, LOAD_FILE, FOR UPDATE, EXPLAIN ANALYZE). String literals and backtick identifiers are ignored by this check.

  2. Server-side read-only transaction — every query runs after SET SESSION TRANSACTION READ ONLY, so MySQL itself rejects writes, including writes made inside stored functions.

Use a MySQL user with only SELECT privileges as well (see below). The validation blocks the known bypasses, but the database privilege is the final guarantee.

For enhanced security, create a dedicated read-only user for the MCP server:

-- Create a read-only user
CREATE USER 'claude_readonly'@'localhost' IDENTIFIED BY 'secure_password';

-- Grant only SELECT permissions on your specific database
GRANT SELECT ON your_database_name.* TO 'claude_readonly'@'localhost';

-- Apply the changes
FLUSH PRIVILEGES;

Troubleshooting

Connection Issues

  1. Verify MySQL is running: Check if your MySQL server is active

  2. Check credentials: Ensure username/password are correct

  3. Network connectivity: Confirm Claude Desktop can reach your MySQL server

Configuration Issues

  1. Restart required: Always restart Claude Desktop after configuration changes

  2. Path accuracy: Ensure the absolute path to dist/index.js is correct

  3. JSON syntax: Validate your claude_desktop_config.json format

Debug Mode

To see server logs, you can run the server manually:

node dist/index.js

File Structure

~/mcp-servers/mysql/
├── src/
│   └── index.ts
├── dist/
│   ├── index.js
│   └── index.d.ts
├── package.json
├── tsconfig.json
└── node_modules/

Dependencies

  • @modelcontextprotocol/sdk: MCP protocol implementation

  • mysql2: Modern MySQL client for Node.js with Promise support

Contributing

Feel free to submit issues and enhancement requests!

License

This project is open source and available under the MIT License.

Support

If you encounter issues:

  1. Check the troubleshooting section above

  2. Verify your MySQL connection independently

  3. Ensure Claude Desktop is updated to the latest version

  4. Review the Claude Desktop MCP documentation


Note: This server is designed for development and analysis purposes. For production use, consider additional security measures and monitoring.

Available Tools

3 tools
connectA

Connect to a MySQL database using a connection string. The connection will be used for subsequent queries until changed.

Inputs: connectionString (required).

disconnectA

Disconnect from the current runtime database and revert to the default environment-configured connection

Inputs: no named parameters.

queryA

Run a read-only SQL query against the currently connected database

Inputs: sql (required), connectionString.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose: connecting, disconnecting, and querying. There is no overlap or ambiguity.

    Naming Consistency5/5

    All tool names are single verbs (connect, disconnect, query), following a consistent pattern. No mixing of conventions.

    Tool Count4/5

    Three tools is minimal but covers the essential operations for a simple MySQL server. While somewhat thin, it is well-scoped and avoids unnecessary tools.

    Completeness3/5

    The tool set covers connect, disconnect, and read-only queries, but lacks any schema exploration or metadata tools (e.g., list tables). This limits usability for agents that need to discover the database structure.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides Claude Desktop with secure access to multiple database connections, allowing users to query MySQL, PostgreSQL, SQLite, and SQL Server databases directly through natural language.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude Desktop to interact with MySQL databases through secure query execution, schema discovery, and multi-database support with configurable read/write permissions and built-in SQL injection protection.
      82 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects AI assistants like Claude Desktop directly to MySQL databases, enabling natural language interaction for schema inspection, data querying, CRUD operations, and database administration tasks.
      8 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude Desktop to interact with MySQL, PostgreSQL, and Redis databases using natural language for data querying and schema analysis. It provides a secure interface with a default read-only mode to prevent unauthorized database modifications.
      133 npm
      945
      MIT