easy-mysql-mcp 1.0.0

package/README.md

@@ -0,0 +1,157 @@
+# easy-mysql-mcp
+
+A lightweight [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that lets AI assistants inspect and query a MySQL database through a safe, structured tool interface.
+
+This project uses Node.js, TypeScript, the official MCP SDK, and `mysql2/promise`. It runs over stdio, so it can be used directly by MCP clients such as Claude Desktop.
+
+## Features
+
+- MySQL connection pooling powered by `mysql2/promise`
+- Read-only query tool for data retrieval
+- Execute tool for data modification statements
+- Schema discovery tools for tables, views, indexes, and triggers
+- Query plan inspection with `EXPLAIN`
+- Current user and privilege inspection
+- stdout protection to prevent non-MCP logs from polluting the stdio protocol
+
+## Requirements
+
+- Node.js 18 or newer
+- npm
+- A reachable MySQL-compatible database
+
+## Installation
+
+Run the server directly with `npx`:
+
+```bash
+npx -y easy-mysql-mcp
+```
+
+For local development after cloning the repository:
+
+```bash
+cd easy-mysql-mcp
+npm install
+npm run build
+```
+
+## Configuration
+
+Configure the server with environment variables. You can provide them through your MCP client configuration or by creating a local `.env` file.
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `MYSQL_HOST` | Yes | - | MySQL host name or IP address |
+| `MYSQL_PORT` | No | `3306` | MySQL port |
+| `MYSQL_USER` | Yes | - | MySQL user name |
+| `MYSQL_PASSWORD` | Yes | - | MySQL password |
+| `MYSQL_DATABASE` | Yes | - | Default database/schema |
+| `MYSQL_CONNECTION_LIMIT` | No | `10` | Maximum number of active pool connections |
+| `MYSQL_MAX_IDLE` | No | `10` | Maximum number of idle pool connections |
+| `MYSQL_IDLE_TIMEOUT` | No | `60000` | Idle connection timeout in milliseconds |
+| `MYSQL_QUEUE_LIMIT` | No | `0` | Maximum queued connection requests, where `0` means unlimited |
+| `MYSQL_WAIT_FOR_CONNECTIONS` | No | `true` | Whether the pool waits when all connections are busy |
+| `MYSQL_ENABLE_KEEP_ALIVE` | No | `true` | Whether TCP keep-alive is enabled |
+| `MYSQL_KEEP_ALIVE_INITIAL_DELAY` | No | `0` | Initial TCP keep-alive delay in milliseconds |
+
+Example `.env`:
+
+```env
+MYSQL_HOST=localhost
+MYSQL_PORT=3306
+MYSQL_USER=root
+MYSQL_PASSWORD=your_password
+MYSQL_DATABASE=your_database
+```
+
+## Usage
+
+Configure your MCP client to launch the package through `npx`.
+
+For local development, build the TypeScript source first:
+
+```bash
+npm run build
+```
+
+Start the MCP server:
+
+```bash
+npm start
+```
+
+The server communicates over stdio and is normally launched by an MCP client rather than run manually.
+
+## Claude Desktop Example
+
+Add the server to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "easy-mysql-mcp": {
+      "command": "npx",
+      "args": ["-y", "easy-mysql-mcp"],
+      "env": {
+        "MYSQL_HOST": "localhost",
+        "MYSQL_PORT": "3306",
+        "MYSQL_USER": "root",
+        "MYSQL_PASSWORD": "your_password",
+        "MYSQL_DATABASE": "your_database"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after updating the configuration.
+
+## Available Tools
+
+| Tool | Description |
+| --- | --- |
+| `mysql_query` | Execute a SQL query intended for data retrieval, such as `SELECT` |
+| `mysql_execute` | Execute a data modification statement, such as `INSERT`, `UPDATE`, or `DELETE` |
+| `explain_query` | Run `EXPLAIN` for a SQL query and return the execution plan |
+| `list_tables` | List base tables in the current database, including approximate row counts and comments |
+| `list_views` | List views in the current database |
+| `describe_table` | Show column information for one or more tables |
+| `describe_index` | Show indexes for a table |
+| `list_triggers` | List triggers in the current database |
+| `get_current_privileges` | Show the current MySQL user and grants |
+
+## Security Notes
+
+- Use a dedicated MySQL user with the minimum permissions your assistant needs.
+- Prefer read-only database credentials if you only need inspection and reporting.
+- Be careful with `mysql_execute`, because it can modify data.
+- Do not commit `.env` files or real database credentials to GitHub.
+- Review generated SQL before running it against production data.
+
+## Development
+
+```bash
+npm run dev
+```
+
+This runs TypeScript in watch mode.
+
+To create a production build:
+
+```bash
+npm run build
+```
+
+## Project Structure
+
+```text
+src/
+  db.ts       MySQL pool and query helpers
+  index.ts    MCP server and tool registration
+  proxy.ts    stdout protection for stdio-based MCP transport
+```
+
+## License
+
+ISC

package/build/db.js

@@ -0,0 +1,30 @@
+import mysql from 'mysql2/promise';
+import dotenv from 'dotenv';
+dotenv.config();
+const { MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE, MYSQL_CONNECTION_LIMIT, MYSQL_MAX_IDLE, MYSQL_IDLE_TIMEOUT, MYSQL_QUEUE_LIMIT, MYSQL_WAIT_FOR_CONNECTIONS, MYSQL_ENABLE_KEEP_ALIVE, MYSQL_KEEP_ALIVE_INITIAL_DELAY, } = process.env;
+if (!MYSQL_HOST || !MYSQL_USER || !MYSQL_PASSWORD || !MYSQL_DATABASE) {
+    console.error('Missing required environment variables for MySQL connection.');
+    process.exit(1);
+}
+export const pool = mysql.createPool({
+    host: MYSQL_HOST,
+    port: MYSQL_PORT ? parseInt(MYSQL_PORT) : 3306,
+    user: MYSQL_USER,
+    password: MYSQL_PASSWORD,
+    database: MYSQL_DATABASE,
+    waitForConnections: MYSQL_WAIT_FOR_CONNECTIONS !== 'false',
+    connectionLimit: MYSQL_CONNECTION_LIMIT ? parseInt(MYSQL_CONNECTION_LIMIT) : 10,
+    maxIdle: MYSQL_MAX_IDLE ? parseInt(MYSQL_MAX_IDLE) : 10,
+    idleTimeout: MYSQL_IDLE_TIMEOUT ? parseInt(MYSQL_IDLE_TIMEOUT) : 60000,
+    queueLimit: MYSQL_QUEUE_LIMIT ? parseInt(MYSQL_QUEUE_LIMIT) : 0,
+    enableKeepAlive: MYSQL_ENABLE_KEEP_ALIVE !== 'false',
+    keepAliveInitialDelay: MYSQL_KEEP_ALIVE_INITIAL_DELAY ? parseInt(MYSQL_KEEP_ALIVE_INITIAL_DELAY) : 0,
+});
+export async function query(sql, params) {
+    const [rows] = await pool.query(sql, params);
+    return rows;
+}
+export async function execute(sql, params) {
+    const [result] = await pool.execute(sql, params);
+    return result;
+}

package/build/index.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+import './proxy.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import * as db from './db.js';
+// Initialize MCP Server
+const server = new McpServer({
+    name: 'easy-mysql-mcp',
+    version: '1.0.0',
+});
+// --- Register Tools ---
+server.registerTool('mysql_query', {
+    description: 'Execute a read-only SQL query (e.g., SELECT). Use this for data retrieval.',
+    inputSchema: z.object({
+        sql: z.string().describe('The SQL query to execute.'),
+    }),
+}, async ({ sql }) => {
+    const results = await db.query(sql);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+    };
+});
+server.registerTool('mysql_execute', {
+    description: 'Execute a data modification SQL statement (e.g., INSERT, UPDATE, DELETE).',
+    inputSchema: z.object({
+        sql: z.string().describe('The SQL statement to execute.'),
+        params: z.array(z.any()).optional().describe('Optional parameters for the statement.'),
+    }),
+}, async ({ sql, params }) => {
+    const result = await db.execute(sql, params);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+});
+server.registerTool('explain_query', {
+    description: 'Run EXPLAIN on a SQL query to analyze its execution plan and performance.',
+    inputSchema: z.object({
+        sql: z.string().describe('The SQL query to explain.'),
+    }),
+}, async ({ sql }) => {
+    const results = await db.query(`EXPLAIN ${sql}`);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+    };
+});
+server.registerTool('list_tables', {
+    description: 'List all base tables in the current database with row counts and comments.',
+    inputSchema: z.object({}),
+}, async () => {
+    const results = await db.query(`
+      SELECT TABLE_NAME, TABLE_ROWS, TABLE_COMMENT 
+      FROM information_schema.TABLES 
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_TYPE = 'BASE TABLE'
+    `);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+    };
+});
+server.registerTool('list_views', {
+    description: 'List all views in the current database.',
+    inputSchema: z.object({}),
+}, async () => {
+    const results = await db.query(`
+      SELECT TABLE_NAME, VIEW_DEFINITION 
+      FROM information_schema.VIEWS 
+      WHERE TABLE_SCHEMA = DATABASE()
+    `);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+    };
+});
+server.registerTool('describe_table', {
+    description: 'Show the schema/structure of one or more specific tables.',
+    inputSchema: z.object({
+        tables: z.array(z.string()).describe('The names of the tables to describe.'),
+    }),
+}, async ({ tables }) => {
+    const results = {};
+    for (const table of tables) {
+        results[table] = await db.query(`DESCRIBE ${table}`);
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+    };
+});
+server.registerTool('describe_index', {
+    description: 'Show indexes for a specific table.',
+    inputSchema: z.object({
+        table: z.string().describe('The name of the table to show indexes for.'),
+    }),
+}, async ({ table }) => {
+    const results = await db.query(`SHOW INDEX FROM ${table}`);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+    };
+});
+server.registerTool('list_triggers', {
+    description: 'List all triggers in the current database.',
+    inputSchema: z.object({}),
+}, async () => {
+    const results = await db.query('SHOW TRIGGERS');
+    return {
+        content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+    };
+});
+server.registerTool('get_current_privileges', {
+    description: 'Check the permissions and grants of the current database user. Useful for debugging access issues.',
+    inputSchema: z.object({}),
+}, async () => {
+    const user = await db.query('SELECT CURRENT_USER() as user');
+    const grants = await db.query('SHOW GRANTS');
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({ currentUser: user, grants }, null, 2)
+            }],
+    };
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('MySQL MCP Server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error in main():', error);
+    process.exit(1);
+});

package/build/proxy.js

@@ -0,0 +1,25 @@
+/**
+ * Stdout Protection Proxy
+ * This module MUST be imported as the very first import in the application.
+ * It intercepts all writes to stdout and redirects non-MCP JSON output to stderr.
+ * This prevents protocol pollution from libraries that log to stdout (like dotenvx).
+ */
+const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+// @ts-ignore
+process.stdout.write = (chunk, encoding, callback) => {
+    if (typeof chunk === 'string' || Buffer.isBuffer(chunk)) {
+        const str = chunk.toString();
+        // Allow MCP JSON-RPC messages and Content-Length headers (used in some transports)
+        if (str.includes('"jsonrpc":"2.0"') || str.includes('Content-Length:')) {
+            return originalStdoutWrite(chunk, encoding, callback);
+        }
+    }
+    // Redirect everything else to stderr
+    return process.stderr.write(chunk, encoding, callback);
+};
+// Also patch console.log to use stderr, just in case
+const originalConsoleLog = console.log;
+console.log = (...args) => {
+    console.error(...args);
+};
+export {};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "easy-mysql-mcp",
+  "version": "1.0.0",
+  "description": "High performance MySQL MCP Server using mysql2",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "easy-mysql-mcp": "build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mysql",
+    "mysql2",
+    "claude"
+  ],
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js",
+    "dev": "tsc --watch",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^17.4.2",
+    "mysql2": "^3.22.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.3"
+  }
+
+}