bundle

Why

The original MCP server is great - until you want to use it from an agent that doesn't speak MCP. mysql-cli keeps the safety model and feature set, but ships as a single binary with JSON by default and stable exit codes, so any agent (Claude Code, Cursor, Codex, Aider, …) can drive it directly over a shell.

• Agent-first - stable JSON envelope + numeric exit codes, designed to be parsed, not read.
• Safe by default - read-only out of the box; writes/DDL/destructive ops need explicit flags.
• Zero-config migration - drop-in for the MCP server's MYSQL_* env vars.
• Multi-datasource - named profiles in TOML, with optional SSH tunneling.
• One binary - go install and you're done.

Installation & Quick Start

Requirements

• Go 1.22+ (to install via go install or build from source)
• A MySQL database you can reach (host/port/user/password)
• For AI Agents: any agent that can run shell commands and parse JSON

Quick Start (Human Users)

Note for AI assistants: If you are an AI Agent helping the user install mysql-cli, jump directly to Quick Start (AI Agent), which contains every step you need to complete.

Install

Option 1 - npx (recommended, no Go toolchain needed):

npx @allenmuu/mysql-cli install      # installs the prebuilt binary to ~/.local/bin
mysql-cli init                       # installs agent skills into detected agents

The npx command downloads the prebuilt binary for your platform from GitHub Releases. Set MYSQL_CLI_MIRROR to use a download mirror. Then run mysql-cli init to install skills.

Option 2 - go install:

go install github.com/AllenMuu/mysql-cli/cmd/mysql-cli@latest

Option 3 - build from source:

git clone https://github.com/AllenMuu/mysql-cli.git
cd mysql-cli
go build -o mysql-cli ./cmd/mysql-cli

Requires Go 1.22+.

Configure & Use

Create ~/.config/mysql-cli/config.toml (see Configure for multiple datasources, env-var compat, and SSH tunneling):

default = "dev"

[datasource.dev]
host = "127.0.0.1"
port = 3306
user = "root"
password = "${MYSQL_DEV_PASSWORD}"
database = "app"

Then query:

mysql-cli query "SELECT * FROM users LIMIT 10"        # read (default)
mysql-cli tables                                       # list tables
mysql-cli schema users                                 # table structure
mysql-cli                                              # enter REPL (human debugging)

Quick Start (AI Agent)

The following steps are for AI Agents. mysql-cli has no browser-based auth, so an agent can complete the entire setup over the shell: install the binary, install the Agent Skills, configure a datasource, then verify and run a query.

Step 1 - Install the binary

go install github.com/AllenMuu/mysql-cli/cmd/mysql-cli@latest

mysql-cli must be on PATH - the skills invoke it by name. Build from source with go build -o mysql-cli ./cmd/mysql-cli if go install is unavailable.

Step 2 - Install Agent Skills

Choose one (all install the three skills). Option 0 is the recommended approach:

Option 0 - mysql-cli init (recommended, no repo clone needed):

mysql-cli init                       # auto-detect installed agents, install to global
mysql-cli init --agent all           # install for all 7 agents
mysql-cli init --project-dir ~/my-project --no-global  # project-level only
mysql-cli init -j                    # JSON output for agents

Option A - installer script (supports all agents below):

./scripts/install-skills.sh                              # auto-detect
./scripts/install-skills.sh --agent all --project-dir ~/my-project

Option B - from the binary (embeds skills, zero external deps):

mysql-cli skill install                       # -> ~/.claude/skills
mysql-cli skill install ~/my-project/.claude/skills

Step 3 - Configure a datasource

Write ~/.config/mysql-cli/config.toml (full format in Configure):

default = "dev"

[datasource.dev]
host = "127.0.0.1"
port = 3306
user = "root"
password = "${MYSQL_DEV_PASSWORD}"
database = "app"

Step 4 - Verify & run

mysql-cli skill check                                 # confirm skills match the binary
mysql-cli query "SELECT * FROM users LIMIT 10"        # JSON by default

The JSON envelope + exit codes are the contract the agent parses - keep -f json (the default) when driving programmatically. See Output and Exit codes.

Configure

~/.config/mysql-cli/config.toml (override with --config):

default = "dev"

[datasource.dev]
host = "127.0.0.1"
port = 3306
user = "root"
password = "${MYSQL_DEV_PASSWORD}"
database = "app"

[datasource.prod]
host = "db.prod.internal"
user = "ro_user"
password = "${MYSQL_PROD_PASSWORD}"
database = "main"
ssl_mode = "REQUIRED"

Resolution priority: CLI flag > env > file > default. Passwords support ${ENV} placeholders. All MYSQL_* environment variables from the original MCP are also supported, so migration is zero-config.

Commands

Flags

Output

JSON by default (agent-friendly):

{"success":true,"data":{"columns":["id"],"rows":[[1]]},"rows_affected":0,"meta":{}}
{"success":false,"error":{"code":"READONLY_VIOLATION","message":"UPDATE requires --write"}}

Switch the human-readable formats with -f table, -f csv, or -f tsv.

Exit codes

Safety

Default read-only. Writes are gated in tiers:

• DML needs --write
• DDL needs --write --ddl
• DROP/TRUNCATE and UPDATE/DELETE without a WHERE need --yes

Identifiers are validated against a strict allowlist (^[a-zA-Z0-9_$]+$); multi-statement input is rejected (use txn). The read-only / multi-statement checks run before a connection is opened, so agents get the right exit code without touching the database.

SSH tunnel

A datasource can tunnel through an SSH bastion instead of connecting directly:

[datasource.prod]
host = "127.0.0.1"
port = 3330
user = "ro_user"
password = "${MYSQL_PROD_PASSWORD}"
database = "main"

[datasource.prod.ssh]
enable = true
host = "bastion.prod"
user = "deploy"
key_path = "~/.ssh/id_ed25519"
remote_host = "db.prod.internal"
remote_port = 3306
local_port = 3330

The tunnel is opened before the DB connection and closed together with it.

Agent Skills

mysql-cli ships Agent Skills so agents can discover and drive it without an MCP runtime. Skills encode trigger conditions, pre-flight checks, command reference, the safety model, and error self-repair - so the agent calls mysql-cli correctly the first time.

There are three skills, following the shared-skill pattern from larksuite/cli:

Other agents

mysql-cli works with any agent that can run shell commands and parse JSON. The installer supports all seven agents below: Claude Code and Cursor use the native SKILL.md / .mdc formats; the others receive the merged skill body appended (idempotently) to their instruction files.

Skill management commands

Setup notes

• mysql-cli must be on PATH - install with go install github.com/AllenMuu/mysql-cli/cmd/mysql-cli@latest, or edit the skill to point at your built binary. / mysql-cli 必须在 PATH 中。
• Config file - the skill expects ~/.config/mysql-cli/config.toml (override with --config). See Configure. / 需配置文件。
• Default JSON output - the skill relies on the JSON envelope + exit codes; keep -f json (the default) when driving programmatically. / 默认 JSON 输出。

Architecture

Strict one-way layering; result is the dependency-free neutral contract that keeps producers and consumers decoupled.

cmd/mysql-cli/main  ->  cli   (cobra wiring + exit-code mapping)
                          │
        config ─-> conn ─-> query ─-> result
          │        │       └─> safety   (pure logic, zero deps)
          │        └─> schema ─> result/safety
          └ env/file        repl  (aggregates query + schema + format)
                            format ← result

Acknowledgements

This project is inspired by and builds upon designcomputer/mysql_mcp_server. Much of the safety model and feature set traces back to that work.

License

Released under the MIT License.