mysql-mcp-server-ms

PyPI package for this MCP server. The GitHub repo is still mysql-mcp-server; the PyPI project is mysql-mcp-server-ms because mysql-mcp-server was already taken on PyPI.

MCP server for MySQL over stdio. Tools: connect_mysql, disconnect, list_databases, list_tables, describe_table, run_query (read-only SQL only).

Use without cloning (recommended for teams)

After the package is on PyPI (or your private index)

Install uv, then run the server with uvx (no repo checkout):

uvx mysql-mcp-server-ms

Pin a version for reproducible MCP configs:

uvx mysql-mcp-server-ms==0.1.0

Cursor — .cursor/mcp.json:

"mysql": {
  "command": "uvx",
  "args": ["mysql-mcp-server-ms"]
}

Claude Code — project .mcp.json or:

claude mcp add --transport stdio mysql -- uvx mysql-mcp-server-ms

Private index (example):

UV_INDEX_URL=https://your-artifact-server/simple uvx mysql-mcp-server-ms

Or set UV_INDEX / PIP_INDEX_URL per uv docs for your org.

Before PyPI: install from Git (no full monorepo clone)

uvx can install the package from a Git URL pointing at this subdirectory (replace ORG, REPO, and branch/tag):

uvx --from "git+https://github.com/ORG/REPO.git#subdirectory=mysql_server&branch=main" mysql-mcp-server-ms

Use a tag or commit SHA instead of branch=main for stable installs.

---

Install from this repo (developers)

cd mysql_server
uv sync
uv run mysql-mcp-server-ms

---

Publishing (maintainers)

So others can run uvx mysql-mcp-server-ms from the default index, the package must be on PyPI (or a private index your team configures).

Option A — GitHub Actions (recommended, no long-lived PyPI token on laptops)

1. One-time on pypi.org: add a pending trusted publisher for project mysql-mcp-server-ms (must match name in pyproject.toml exactly) → Settings → Publishing → workflow publish-mysql-mcp-server.yml on this repo (see comments in .github/workflows/publish-mysql-mcp-server.yml).
2. Bump version in pyproject.toml and merge to the default branch.
3. Trigger the workflow:
   • GitHub → Actions → Publish mysql-mcp-server-ms to PyPI → Run workflow, or
   • Push tag mysql-mcp-server-ms-v0.1.0 (prefix mysql-mcp-server-ms-v + semver from pyproject.toml, e.g. version 0.1.0 → tag mysql-mcp-server-ms-v0.1.0).
4. Confirm on PyPI.

If your pending publisher used a different spelling (e.g. mysql_mcp_server_ms), remove it on PyPI and create a new one whose project name matches the name field in pyproject.toml (mysql-mcp-server-ms).

Option B — From your machine

1. Bump version in pyproject.toml.

2. Remove stray *.egg-info under src/ if present (rm -rf src/*.egg-info).

3. Build and upload:

   cd mysql_server
   uv build
   uv publish
   

   Configure credentials via uv publish (UV_PUBLISH_TOKEN, or keyring / ~/.pypirc).

---

Prerequisites

• Python 3.10+
• uv on PATH (for uvx / uv sync)
• Network access to MySQL (VPN if internal)

Installing uv

curl -LsSf https://astral.sh/uv/install.sh | sh
# or: brew install uv
uv --version

---

Cursor (monorepo / editable install)

If you develop inside the repo (clone path may be mysql-mcp-server):

"mysql": {
  "command": "uv",
  "args": [
    "--directory",
    "/absolute/path/to/mysql-mcp-server/mysql_server",
    "run",
    "mysql-mcp-server-ms"
  ]
}

Legacy: .venv/bin/python3 + server.py shim is supported after uv sync.

---

Claude Code (monorepo + REPO_ROOT)

If your monorepo uses a root env var, point it at this package directory, for example:

export REPO_ROOT="/absolute/path/to/mysql-mcp-server"
claude mcp add --transport stdio mysql -- \
  uv --directory "$REPO_ROOT/mysql_server" run mysql-mcp-server-ms

---

Security

• Prefer read-only MySQL users.
• Use VPN for internal DB hosts.
• Never commit passwords; use connect_mysql in-session or your secret manager.

Optional: Index-aware query enforcement (reject full scans + non-indexed predicates)

This MCP server can enforce a stricter performance policy for SELECT queries (including WITH ... SELECT):

• It parses WHERE and JOIN ... ON predicates.
• For each predicate column, it checks INFORMATION_SCHEMA.STATISTICS to see whether that column belongs to any index on the referenced table.
• It also runs EXPLAIN and rejects the query if MySQL reports a full table scan (type = ALL).

Enable it by setting an env var when starting the MCP server:

"mysql": {
  "command": "uvx",
  "args": ["mysql-mcp-server-ms"],
  "env": {
    "MCP_MYSQL_ENFORCE_INDEXED_COLUMNS": "1"
  }
}

If a query is rejected, you’ll get a message listing the non-indexed predicate columns (best-effort) and suggestions like “add an index” or “rewrite WHERE/JOIN to use an indexed column”.

Note: the mapping from SQL column references to tables is best-effort. For complex queries (subqueries/CTEs with ambiguous column qualifiers), the server may fall back to an EXPLAIN-only check and allow the query if no full scan is detected.