# MySQL Reader (read-only)

Read-only MySQL tools for `xmcp`. Connect via a connection-string env var; all operations are read-only.

### Prerequisites

- Node 20+
- pnpm

### Install & build

```bash
pnpm i
pnpm build
```

### Configure database connection

Set one of (first found wins): `MYSQL_URL`, `MYSQL_CONNECTION_STRING`, or `DATABASE_URL`.

```bash
export MYSQL_URL="mysql://user:password@localhost:3306/mydb"
```

**SSL** is controlled by `MYSQL_SSL` (default: `"true"`):

| Value | Behavior |
|---|---|
| `true` (default) | Encrypted, skips cert hostname validation — use when connecting through a tunnel or proxy |
| `strict` | Encrypted, validates server certificate — use for direct connections with a valid cert |
| `false` | No SSL — local dev only |

```bash
export MYSQL_SSL=true    # tunnel / hosted DB (default)
export MYSQL_SSL=strict  # direct connection, valid cert
export MYSQL_SSL=false   # local dev, no SSL
```

### Use in Cursor (STDIO)

**Via npx** (after publishing to npm — no local clone needed):

```json
{
  "mcpServers": {
    "mysql-reader": {
      "command": "npx",
      "args": ["-y", "mysql-db-reader"],
      "env": { "MYSQL_URL": "mysql://user:password@host:3306/db" }
    }
  }
}
```

**Local build** (after `pnpm build`):

```json
{
  "mcpServers": {
    "mysql-reader": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/mysql-db-reader/dist/stdio.js"],
      "env": { "MYSQL_URL": "mysql://user:password@host:3306/db" }
    }
  }
}
```

### Use via HTTP (optional)

```bash
pnpm dev
```

Then point your MCP client to `http://localhost:3002/mcp`.

To use a different port (e.g., 3001):

```bash
export MYSQL_URL="mysql://user:password@localhost:3306/mydb"
PORT=3001 pnpm dev
```

Example HTTP client config (TOML):

```toml
[mcp_servers.mysql-reader]
transport = "http"
url = "http://127.0.0.1:3001/mcp"
project = "/ABSOLUTE/PATH/TO/your/project"
```

### Tools

- `mysql_list_databases(includeSystem=false)` — list databases
- `mysql_list_tables(database, includeViews=true)` — list tables/views
- `mysql_get_table_schema(database, table)` — columns/constraints/indexes
- `mysql_preview_table(database, table, limit=50, orderBy?)` — sample rows
- `mysql_query(sql, params?)` — read-only SQL (SELECT/SHOW/DESC/EXPLAIN/WITH), max 10k rows
- `mysql_explain_query(sql)` — EXPLAIN a SELECT

### Codex compatibility

Tool names use lowercase snake_case (underscores, no dots) to comply with Codex's tool name pattern `^[a-zA-Z0-9_-]+$` (Codex models prefer lower_snake). See: [MCP in Codex docs](https://github.com/openai/codex/blob/main/docs/advanced.md#model-context-protocol-mcp)

Read-only is enforced via session settings and SQL guards.

Docs: [xmcp docs](https://xmcp.dev/docs)