@kmusialik/mysql-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krzysztof Musialik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @kmusialik/mysql-mcp-server
+
+Read-only [MCP](https://modelcontextprotocol.io) server for MySQL. It lets Claude and other MCP clients browse schemas and run `SELECT` queries. It can't change your data.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_databases` | Lists the databases visible to the user |
+| `list_tables` | Lists tables and views, with approximate row counts |
+| `describe_table` | Shows a table's columns, types, keys and indexes |
+| `query` | Runs one read-only statement (`SELECT`, `SHOW`, `DESCRIBE`, `EXPLAIN`, `WITH`) |
+
+Protections:
+- only allowed statement types, one statement per call
+- every query runs in `START TRANSACTION READ ONLY` and is then rolled back
+- row limit and query timeout
+
+For the best protection, also connect as a MySQL user that has only `SELECT` privileges.
+
+## Configuration
+
+| Variable | Default |
+|---|---|
+| `MYSQL_HOST` | `localhost` |
+| `MYSQL_PORT` | `3306` |
+| `MYSQL_USER` | `root` |
+| `MYSQL_PASSWORD` | _(empty)_ |
+| `MYSQL_DATABASE` | _(none; pass `database` to the tools)_ |
+| `MYSQL_SSL` | `false` |
+| `MYSQL_SSL_REJECT_UNAUTHORIZED` | `true` |
+| `MYSQL_MAX_ROWS` | `1000` |
+| `MYSQL_QUERY_TIMEOUT_MS` | `30000` |
+
+`DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASS` and `DB_NAME` also work.
+
+## Usage
+
+### Claude Code
+
+```bash
+claude mcp add mysql \
+  -e MYSQL_HOST=localhost -e MYSQL_USER=reader -e MYSQL_PASSWORD=secret -e MYSQL_DATABASE=shop \
+  -- npx -y @kmusialik/mysql-mcp-server
+```
+
+### Claude Desktop / Cursor (`mcpServers`)
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": ["-y", "@kmusialik/mysql-mcp-server"],
+      "env": {
+        "MYSQL_HOST": "localhost",
+        "MYSQL_USER": "reader",
+        "MYSQL_PASSWORD": "secret",
+        "MYSQL_DATABASE": "shop"
+      }
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import mysql from "mysql2/promise";
+import { z } from "zod";
+
+const env = (...keys) => keys.map((k) => process.env[k]).find((v) => v !== undefined && v !== "");
+
+const config = {
+  host: env("MYSQL_HOST", "DB_HOST") ?? "localhost",
+  port: Number(env("MYSQL_PORT", "DB_PORT") ?? 3306),
+  user: env("MYSQL_USER", "DB_USER") ?? "root",
+  password: env("MYSQL_PASSWORD", "MYSQL_PASS", "DB_PASS", "DB_PASSWORD") ?? "",
+  database: env("MYSQL_DATABASE", "DB_NAME"),
+  ssl: env("MYSQL_SSL") === "true" ? { rejectUnauthorized: env("MYSQL_SSL_REJECT_UNAUTHORIZED") !== "false" } : undefined,
+};
+const MAX_ROWS = Number(env("MYSQL_MAX_ROWS") ?? 1000);
+const QUERY_TIMEOUT_MS = Number(env("MYSQL_QUERY_TIMEOUT_MS") ?? 30000);
+
+const pool = mysql.createPool({
+  ...config,
+  waitForConnections: true,
+  connectionLimit: 5,
+  multipleStatements: false,
+  dateStrings: true,
+  supportBigNumbers: true,
+  bigNumberStrings: true,
+});
+
+const READ_ONLY_PREFIX = /^\s*(select|show|describe|desc|explain|with)\b/i;
+
+function stripComments(sql) {
+  return sql
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+    .replace(/(--\s|#)[^\n]*/g, " ")
+    .trim();
+}
+
+// Every query runs inside a READ ONLY transaction that is always rolled back,
+// so even a statement that slips past the prefix check cannot modify data.
+async function runReadOnly(sql, params = []) {
+  const conn = await pool.getConnection();
+  try {
+    await conn.query("START TRANSACTION READ ONLY");
+    const [rows, fields] = await conn.query({ sql, values: params, timeout: QUERY_TIMEOUT_MS });
+    return { rows, fields };
+  } finally {
+    await conn.query("ROLLBACK").catch(() => {});
+    conn.release();
+  }
+}
+
+const text = (value) => ({
+  content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }],
+});
+const fail = (err) => ({ content: [{ type: "text", text: `Error: ${err.message ?? err}` }], isError: true });
+
+const ident = (name) => "`" + String(name).replace(/`/g, "``") + "`";
+
+const server = new McpServer({ name: "mysql-mcp-server", version: "1.0.0" });
+
+server.registerTool(
+  "list_databases",
+  {
+    title: "List databases",
+    description: "List all databases visible to the configured MySQL user.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+  },
+  async () => {
+    try {
+      const { rows } = await runReadOnly("SHOW DATABASES");
+      return text(rows.map((r) => r.Database));
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+
+server.registerTool(
+  "list_tables",
+  {
+    title: "List tables",
+    description: "List tables (and views) in a database, with approximate row counts and comments.",
+    inputSchema: {
+      database: z.string().optional().describe("Database name. Defaults to MYSQL_DATABASE."),
+    },
+    annotations: { readOnlyHint: true },
+  },
+  async ({ database }) => {
+    try {
+      const db = database ?? config.database;
+      if (!db) throw new Error("No database given and MYSQL_DATABASE is not set.");
+      const { rows } = await runReadOnly(
+        `SELECT TABLE_NAME AS name, TABLE_TYPE AS type, TABLE_ROWS AS approx_rows, TABLE_COMMENT AS comment
+           FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? ORDER BY TABLE_NAME`,
+        [db]
+      );
+      return text(rows);
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+
+server.registerTool(
+  "describe_table",
+  {
+    title: "Describe table",
+    description: "Show columns, types, keys and indexes of a table.",
+    inputSchema: {
+      table: z.string().describe("Table name"),
+      database: z.string().optional().describe("Database name. Defaults to MYSQL_DATABASE."),
+    },
+    annotations: { readOnlyHint: true },
+  },
+  async ({ table, database }) => {
+    try {
+      const db = database ?? config.database;
+      if (!db) throw new Error("No database given and MYSQL_DATABASE is not set.");
+      const { rows: columns } = await runReadOnly(
+        `SELECT COLUMN_NAME AS name, COLUMN_TYPE AS type, IS_NULLABLE AS nullable, COLUMN_KEY AS \`key\`,
+                COLUMN_DEFAULT AS \`default\`, EXTRA AS extra, COLUMN_COMMENT AS comment
+           FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? ORDER BY ORDINAL_POSITION`,
+        [db, table]
+      );
+      if (columns.length === 0) throw new Error(`Table ${db}.${table} not found.`);
+      const { rows: indexes } = await runReadOnly(`SHOW INDEX FROM ${ident(db)}.${ident(table)}`);
+      return text({
+        columns,
+        indexes: indexes.map((i) => ({ name: i.Key_name, column: i.Column_name, unique: i.Non_unique === 0, seq: i.Seq_in_index })),
+      });
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+
+server.registerTool(
+  "query",
+  {
+    title: "Run read-only SQL",
+    description:
+      `Run a single read-only SQL statement (SELECT, SHOW, DESCRIBE, EXPLAIN, WITH). ` +
+      `Results are capped at ${MAX_ROWS} rows. Use ? placeholders with 'params' for values.`,
+    inputSchema: {
+      sql: z.string().describe("A single read-only SQL statement"),
+      params: z.array(z.union([z.string(), z.number(), z.boolean(), z.null()])).optional().describe("Values for ? placeholders"),
+      database: z.string().optional().describe("Database to USE for this query. Defaults to MYSQL_DATABASE."),
+    },
+    annotations: { readOnlyHint: true },
+  },
+  async ({ sql, params, database }) => {
+    try {
+      const cleaned = stripComments(sql).replace(/;\s*$/, "");
+      if (!READ_ONLY_PREFIX.test(cleaned)) {
+        throw new Error("Only SELECT, SHOW, DESCRIBE, EXPLAIN and WITH statements are allowed.");
+      }
+      if (cleaned.includes(";")) throw new Error("Multiple statements are not allowed.");
+
+      const conn = await pool.getConnection();
+      try {
+        const db = database ?? config.database;
+        if (db) await conn.query(`USE ${ident(db)}`);
+        await conn.query("START TRANSACTION READ ONLY");
+        const [rows] = await conn.query({ sql: cleaned, values: params ?? [], timeout: QUERY_TIMEOUT_MS });
+        const list = Array.isArray(rows) ? rows : [rows];
+        const truncated = list.length > MAX_ROWS;
+        return text({
+          rowCount: list.length,
+          truncated,
+          rows: truncated ? list.slice(0, MAX_ROWS) : list,
+        });
+      } finally {
+        await conn.query("ROLLBACK").catch(() => {});
+        conn.release();
+      }
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+
+async function shutdown() {
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`mysql-mcp-server connected to ${config.user}@${config.host}:${config.port}${config.database ? "/" + config.database : ""}`);

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@kmusialik/mysql-mcp-server",
+  "version": "1.0.0",
+  "description": "Read-only MCP server for MySQL — let Claude and other MCP clients explore and query your database safely",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "mysql-mcp-server": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "mysql",
+    "model-context-protocol",
+    "claude",
+    "llm",
+    "read-only"
+  ],
+  "author": "Krzysztof Musialik",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "mysql2": "^3.24.4",
+    "zod": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}