mysql-mcp

mysql-mcp is a read-only MySQL MCP server that can be used by Codex, Claude Code, and other Model Context Protocol clients.

It exposes two tools:

• query_mysql: execute a read-only SQL query against a configured datasource
• list_datasources: list the available datasource names from the config file

Features

• Read-only query workflow through MCP stdio transport
• Multiple datasource definitions in one YAML config file
• Simple installation from PyPI once published
• Works with Codex and Claude Code global MCP configuration

Installation

From PyPI

pipx install mysql-mcp

Or with uv:

uv tool install mysql-mcp

Local development

python3 -m pip install -e ".[dev]"

Configuration

Create a YAML config file. You can start from config.example.yaml:

datasources:
  dev:
    host: "127.0.0.1"
    port: 3306
    user: "mysql"
    password: "${MYSQL_PASSWORD}"
    database: "app_dev"
    pool_size: 5
    pool_name: "dev_pool"

query:
  default_timeout: 30
  max_rows: 10000

The MCP process must receive any referenced environment variables such as MYSQL_PASSWORD.

Running the server

cp config.example.yaml config.yaml
mysql-mcp /absolute/path/to/config.yaml

Codex setup

Add it as a global MCP server:

codex mcp add mysql-mcp \
  --env MYSQL_PASSWORD=your-password \
  -- mysql-mcp /absolute/path/to/config.yaml

If you prefer not to preinstall the package, you can also run it through uvx:

codex mcp add mysql-mcp \
  --env MYSQL_PASSWORD=your-password \
  -- uvx mysql-mcp /absolute/path/to/config.yaml

Claude Code setup

Add this to ~/.claude/settings.json:

{
  "mcpServers": {
    "mysql-mcp": {
      "type": "stdio",
      "command": "mysql-mcp",
      "args": ["/absolute/path/to/config.yaml"],
      "env": {
        "MYSQL_PASSWORD": "your-password"
      }
    }
  }
}

Or use uvx:

{
  "mcpServers": {
    "mysql-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mysql-mcp", "/absolute/path/to/config.yaml"],
      "env": {
        "MYSQL_PASSWORD": "your-password"
      }
    }
  }
}

Publish to PyPI

1. Update the version in pyproject.toml.
2. Build the package:

python3 -m build

1. Upload to TestPyPI first:

python3 -m twine upload --repository testpypi dist/*

1. Upload to PyPI:

python3 -m twine upload dist/*

Development

Run tests:

pytest -q

Build artifacts:

python3 -m build