MySQL Legacy MCP

MCP server for legacy MySQL 5.0–5.6 databases through stdio. The package is on npm as mysql-legacy-mcp and in the official MCP Registry as io.github.Rufflet/mysql-legacy-mcp.

It uses MySQL 5.1-compatible SQL and SHOW metadata queries. Live MCP tests cover MySQL 5.0.51a, 5.1.73, 5.5.62, and 5.6.51. It is deliberately small: read-only by default, with INSERT/UPDATE/DELETE/DDL as opt-in tools disabled unless explicitly enabled; no TLS configuration, and no custom authentication or charset options.

Is this for you?

• You need an AI agent to inspect a MySQL 5.0, 5.1, 5.5, or 5.6 database.
• Your current MySQL MCP server assumes MySQL 5.7+, JSON functions, or newer information_schema fields.
• You need schema inspection and SELECT queries, with write operations off by default and opt-in per statement type.

If you are seeing ER_NOT_SUPPORTED_AUTH_MODE, HANDSHAKE_INSECURE_AUTH, Old password authentication is not supported, legacy TLS errors, or garbled cp1251 / latin1 text, read Troubleshooting first. Those symptoms are not all solved by this package.

Requirements

• Node.js 18.14.1 or later
• npm
• A dedicated MySQL account with only the required read and metadata privileges

Where it is listed

Installation is always local stdio via npm (npx -y mysql-legacy-mcp). Directory pages do not make that faster; they are discovery indexes. The official MCP Registry is the machine-readable source (io.github.Rufflet/mysql-legacy-mcp) that aggregators ingest, including env-var metadata from server.json. Clients that speak that registry can pre-fill configuration from it.

• npm
• Official MCP Registry
• Glama
• TensorBlock MCP Index
• Awesome MCP Servers
• Awesome MCP ZH

Maintainer submission status for other directories is in docs/RELEASE_CHECKLIST.md.

Quick install

Claude Code

claude mcp add --transport stdio mysql-legacy \
  --env MYSQL_LEGACY_HOST=127.0.0.1 \
  --env MYSQL_LEGACY_USER=legacy_reader \
  --env MYSQL_LEGACY_PASSWORD=replace-with-a-secret \
  --env MYSQL_LEGACY_DATABASE=legacy_app \
  -- npx -y mysql-legacy-mcp

Codex

codex mcp add mysql-legacy \
  --env MYSQL_LEGACY_HOST=127.0.0.1 \
  --env MYSQL_LEGACY_USER=legacy_reader \
  --env MYSQL_LEGACY_PASSWORD=replace-with-a-secret \
  --env MYSQL_LEGACY_DATABASE=legacy_app \
  -- npx -y mysql-legacy-mcp

Cursor and other clients

{
  "mcpServers": {
    "mysql-legacy": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mysql-legacy-mcp"],
      "env": {
        "MYSQL_LEGACY_HOST": "127.0.0.1",
        "MYSQL_LEGACY_USER": "legacy_reader",
        "MYSQL_LEGACY_PASSWORD": "replace-with-a-secret",
        "MYSQL_LEGACY_DATABASE": "legacy_app"
      }
    }
  }
}

Use the schema required by your client. Full copy-paste instructions for Claude Desktop, Codex, VS Code, Windsurf, Gemini, Trae, Qoder, and more are in the Installation guide.

Compatibility

Each tested target passed all 11 tools — the 7 read-only tools plus the 4 opt-in write tools, with MYSQL_LEGACY_ALLOW_* flags checked both left at their default false and explicitly enabled — through a real MCP stdio session. On MySQL 5.6.5 and later, this also exercised the actual START TRANSACTION READ ONLY path used by mysql_legacy_select; below that version it exercised the silent plain-query fallback. Exact sources, test conditions, and the MySQL 8.0 boundary are recorded in the compatibility audit. This does not cover pre-4.1 old_password, custom connection charsets, TLS, or your server's exact patch level.

Compared with modern MySQL MCP servers

This is a compatibility distinction, not a benchmark: choose the modern server for its modern-database features.

Features

• Read-only SELECT tool with parser checks and result-size limits, wrapped in a read-only transaction on MySQL 5.6.5+
• SHOW-based database, table, column, CREATE TABLE, and index inspection
• Opt-in INSERT/UPDATE/DELETE/DDL tools, each disabled by default and gated by its own MYSQL_LEGACY_ALLOW_* flag; UPDATE and DELETE always require a WHERE clause
• A small pooled set of MySQL connections (MYSQL_LEGACY_POOL_SIZE); no reliance on CTEs, JSON functions, or modern metadata columns

Tools

Documentation

• Installation guide — client-specific setup
• Configuration — environment variables, privileges, and security limits
• Troubleshooting — authentication, TLS, encoding, and startup errors
• Compatibility audit — reproducible version evidence
• Roadmap — deliberately deferred work and why

Why this exists

This project came from a QA/fullstack workflow that needed AI-assisted inspection of a production MySQL 5.1 database. It is a focused utility for exploring legacy schemas and preparing migrations.

Contributing

See CONTRIBUTING.md for how to propose changes, run checks locally, and what evidence a compatibility claim needs. Quick start:

npm ci
npm run check
npm run smoke:static

For authorized database testing, see the smoke-test instructions in the compatibility audit.

License

MIT.