@cano721/mysql-mcp-server 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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,285 @@
+[![npm version](https://img.shields.io/npm/v/@cano721/mysql-mcp-server?color=blue)](https://www.npmjs.com/package/@cano721/mysql-mcp-server)
+
+
+# MySQL Database Access MCP Server (@cano721/mysql-mcp-server)
+
+This MCP server provides read-only access to MySQL databases. It allows you to:
+
+- List available databases
+- List tables in a database
+- Describe table schemas
+- Execute read-only SQL queries
+
+## Security Features
+
+- **Read-only access**: Only SELECT, SHOW, DESCRIBE, and EXPLAIN statements are allowed
+- **Query validation**: Prevents SQL injection and blocks any data modification attempts
+- **Query timeout**: Prevents long-running queries from consuming resources
+- **Row limit**: Prevents excessive data return
+
+## Installation
+
+### 1. Install using one of these methods:
+
+#### Install from NPM
+
+```bash
+# Install globally
+npm install -g @cano721/mysql-mcp-server
+
+# Or install locally in your project
+npm install @cano721/mysql-mcp-server
+```
+
+#### Build from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/cano721/mysql-mcp-server.git
+cd mysql-mcp-server
+
+# Install dependencies and build
+npm install
+npm run build
+```
+
+#### Install via Smithery
+
+To install MySQL Database Access MCP Server for Claude AI automatically via Smithery:
+
+```bash
+npx -y @smithery/cli install @cano721/mysql-mcp-server --client claude
+```
+
+### 2. Configure environment variables
+
+The server requires the following environment variables:
+
+- `MYSQL_HOST`: Database server hostname
+- `MYSQL_PORT`: Database server port (default: 3306)
+- `MYSQL_USER`: Database username
+- `MYSQL_PASSWORD`: Database password (optional, but recommended for secure connections)
+- `MYSQL_DATABASE`: Default database name (optional)
+
+### 3. Add to MCP settings
+
+Add the following configuration to your MCP settings file:
+
+If you installed via npm (Option 1):
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": ["@cano721/mysql-mcp-server"],
+      "env": {
+        "MYSQL_HOST": "your-mysql-host",
+        "MYSQL_PORT": "3306",
+        "MYSQL_USER": "your-mysql-user",
+        "MYSQL_PASSWORD": "your-mysql-password",
+        "MYSQL_DATABASE": "your-default-database"
+      },
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+If you built from source (Option 2):
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "node",
+      "args": ["/path/to/mysql-mcp-server/build/index.js"],
+      "env": {
+        "MYSQL_HOST": "your-mysql-host",
+        "MYSQL_PORT": "3306",
+        "MYSQL_USER": "your-mysql-user",
+        "MYSQL_PASSWORD": "your-mysql-password",
+        "MYSQL_DATABASE": "your-default-database"
+      },
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+## Available Tools
+
+### list_databases
+
+Lists all accessible databases on the MySQL server.
+
+**Parameters**: None
+
+**Example**:
+```json
+{
+  "server_name": "mysql",
+  "tool_name": "list_databases",
+  "arguments": {}
+}
+```
+
+### list_tables
+
+Lists all tables in a specified database.
+
+**Parameters**:
+- `database` (optional): Database name (uses default if not specified)
+
+**Example**:
+```json
+{
+  "server_name": "mysql",
+  "tool_name": "list_tables",
+  "arguments": {
+    "database": "my_database"
+  }
+}
+```
+
+### describe_table
+
+Shows the schema for a specific table.
+
+**Parameters**:
+- `database` (optional): Database name (uses default if not specified)
+- `table` (required): Table name
+
+**Example**:
+```json
+{
+  "server_name": "mysql",
+  "tool_name": "describe_table",
+  "arguments": {
+    "database": "my_database",
+    "table": "my_table"
+  }
+}
+```
+
+### execute_query
+
+Executes a read-only SQL query.
+
+**Parameters**:
+- `query` (required): SQL query (only SELECT, SHOW, DESCRIBE, and EXPLAIN statements are allowed)
+- `database` (optional): Database name (uses default if not specified)
+
+**Example**:
+```json
+{
+  "server_name": "mysql",
+  "tool_name": "execute_query",
+  "arguments": {
+    "database": "my_database",
+    "query": "SELECT * FROM my_table LIMIT 10"
+  }
+}
+```
+
+## Advanced Connection Pool Configuration
+
+For more control over the MySQL connection pool behavior, you can configure additional parameters:
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": ["@cano721/mysql-mcp-server"],
+      "env": {
+        "MYSQL_HOST": "your-mysql-host",
+        "MYSQL_PORT": "3306",
+        "MYSQL_USER": "your-mysql-user",
+        "MYSQL_PASSWORD": "your-mysql-password",
+        "MYSQL_DATABASE": "your-default-database",
+        
+        "MYSQL_CONNECTION_LIMIT": "10",
+        "MYSQL_QUEUE_LIMIT": "0",
+        "MYSQL_CONNECT_TIMEOUT": "10000",
+        "MYSQL_IDLE_TIMEOUT": "60000",
+        "MYSQL_MAX_IDLE": "10"
+      },
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+These advanced options allow you to:
+
+- `MYSQL_CONNECTION_LIMIT`: Control the maximum number of connections in the pool (default: 10)
+- `MYSQL_QUEUE_LIMIT`: Set the maximum number of connection requests to queue (default: 0, unlimited)
+- `MYSQL_CONNECT_TIMEOUT`: Adjust the connection timeout in milliseconds (default: 10000)
+- `MYSQL_IDLE_TIMEOUT`: Configure how long a connection can be idle before being released (in milliseconds)
+- `MYSQL_MAX_IDLE`: Set the maximum number of idle connections to keep in the pool
+
+
+## Testing
+
+The server includes test scripts to verify functionality with your MySQL setup:
+
+### 1. Setup Test Database
+
+This script creates a test database, table, and sample data:
+
+```bash
+# Set your MySQL credentials as environment variables
+export MYSQL_HOST=localhost
+export MYSQL_PORT=3306
+export MYSQL_USER=your_username
+export MYSQL_PASSWORD=your_password
+
+# Run the setup script
+npm run test:setup
+```
+
+### 2. Test MCP Tools
+
+This script tests each of the MCP tools against the test database:
+
+```bash
+# Set your MySQL credentials as environment variables
+export MYSQL_HOST=localhost
+export MYSQL_PORT=3306
+export MYSQL_USER=your_username
+export MYSQL_PASSWORD=your_password
+export MYSQL_DATABASE=mcp_test_db
+
+# Run the tools test script
+npm run test:tools
+```
+
+### 3. Run All Tests
+
+To run both setup and tool tests:
+
+```bash
+# Set your MySQL credentials as environment variables
+export MYSQL_HOST=localhost
+export MYSQL_PORT=3306
+export MYSQL_USER=your_username
+export MYSQL_PASSWORD=your_password
+
+# Run all tests
+npm test
+```
+
+## Troubleshooting
+
+If you encounter issues:
+
+1. Check the server logs for error messages
+2. Verify your MySQL credentials and connection details
+3. Ensure your MySQL user has appropriate permissions
+4. Check that your query is read-only and properly formatted
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details.

package/build/connection.js

@@ -0,0 +1,128 @@
+/**
+ * MySQL connection management for MCP server
+ */
+import mysql from 'mysql2/promise';
+// Default connection pool configuration
+const DEFAULT_PORT = 3306; // Default MySQL port
+const DEFAULT_TIMEOUT = 10000; // Default connection timeout in milliseconds
+const DEFAULT_CONNECTION_LIMIT = 10; // Default maximum number of connections in the pool
+const DEFAULT_QUEUE_LIMIT = 0; // Default maximum number of connection requests to queue (0 = unlimited)
+const DEFAULT_ROW_LIMIT = 1000; // Default row limit for query results
+/**
+ * Create a MySQL connection pool
+ */
+export function createConnectionPool(config) {
+    console.error('[Setup] Creating MySQL connection pool');
+    try {
+        // Create connection options with defaults
+        const poolConfig = {
+            host: config.host,
+            port: config.port,
+            user: config.user,
+            waitForConnections: true,
+            connectionLimit: config.connectionLimit ?? DEFAULT_CONNECTION_LIMIT,
+            queueLimit: config.queueLimit ?? DEFAULT_QUEUE_LIMIT,
+            connectTimeout: config.connectTimeout ?? DEFAULT_TIMEOUT,
+        };
+        // Add password if provided
+        if (config.password !== undefined) {
+            poolConfig.password = config.password;
+        }
+        // Add database if provided
+        if (config.database) {
+            poolConfig.database = config.database;
+        }
+        // Add idleTimeout if provided
+        if (config.idleTimeout !== undefined) {
+            poolConfig.idleTimeout = config.idleTimeout;
+        }
+        // Add maxIdle if provided
+        if (config.maxIdle !== undefined) {
+            poolConfig.maxIdle = config.maxIdle;
+        }
+        return mysql.createPool(poolConfig);
+    }
+    catch (error) {
+        console.error('[Error] Failed to create connection pool:', error);
+        throw error;
+    }
+}
+/**
+ * Execute a query with error handling and logging
+ */
+export async function executeQuery(pool, sql, params = [], database) {
+    console.error(`[Query] Executing: ${sql}`);
+    let connection = null;
+    try {
+        // Get connection from pool
+        connection = await pool.getConnection();
+        // Use specific database if provided
+        if (database) {
+            console.error(`[Query] Using database: ${database}`);
+            await connection.query(`USE \`${database}\``);
+        }
+        // Execute query with timeout
+        const [rows, fields] = await Promise.race([
+            connection.query(sql, params),
+            new Promise((_, reject) => {
+                setTimeout(() => reject(new Error('Query timeout')), DEFAULT_TIMEOUT);
+            }),
+        ]);
+        // Apply row limit if result is an array
+        const limitedRows = Array.isArray(rows) && rows.length > DEFAULT_ROW_LIMIT
+            ? rows.slice(0, DEFAULT_ROW_LIMIT)
+            : rows;
+        // Log result summary
+        console.error(`[Query] Success: ${Array.isArray(rows) ? rows.length : 1} rows returned`);
+        return { rows: limitedRows, fields };
+    }
+    catch (error) {
+        console.error('[Error] Query execution failed:', error);
+        throw error;
+    }
+    finally {
+        // Release connection back to pool
+        if (connection) {
+            connection.release();
+        }
+    }
+}
+/**
+ * Get MySQL connection configuration from environment variables
+ */
+export function getConfigFromEnv() {
+    const host = process.env.MYSQL_HOST;
+    const portStr = process.env.MYSQL_PORT;
+    const user = process.env.MYSQL_USER;
+    const password = process.env.MYSQL_PASSWORD;
+    const database = process.env.MYSQL_DATABASE;
+    // Connection pool options
+    const connectionLimitStr = process.env.MYSQL_CONNECTION_LIMIT;
+    const queueLimitStr = process.env.MYSQL_QUEUE_LIMIT;
+    const connectTimeoutStr = process.env.MYSQL_CONNECT_TIMEOUT;
+    const idleTimeoutStr = process.env.MYSQL_IDLE_TIMEOUT;
+    const maxIdleStr = process.env.MYSQL_MAX_IDLE;
+    if (!host)
+        throw new Error('MYSQL_HOST environment variable is required');
+    if (!user)
+        throw new Error('MYSQL_USER environment variable is required');
+    const port = portStr ? parseInt(portStr, 10) : DEFAULT_PORT;
+    // Parse connection pool options (all optional)
+    const connectionLimit = connectionLimitStr ? parseInt(connectionLimitStr, 10) : undefined;
+    const queueLimit = queueLimitStr ? parseInt(queueLimitStr, 10) : undefined;
+    const connectTimeout = connectTimeoutStr ? parseInt(connectTimeoutStr, 10) : undefined;
+    const idleTimeout = idleTimeoutStr ? parseInt(idleTimeoutStr, 10) : undefined;
+    const maxIdle = maxIdleStr ? parseInt(maxIdleStr, 10) : undefined;
+    return {
+        host,
+        port,
+        user,
+        password,
+        database,
+        connectionLimit,
+        queueLimit,
+        connectTimeout,
+        idleTimeout,
+        maxIdle
+    };
+}

package/build/index.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * MySQL Database Access MCP Server
+ *
+ * This MCP server provides read-only access to MySQL databases.
+ * It allows:
+ * - Listing available databases
+ * - Listing tables in a database
+ * - Describing table schemas
+ * - Executing read-only SQL queries
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { createConnectionPool, executeQuery, getConfigFromEnv } from './connection.js';
+import { validateQuery } from './validators.js';
+// Create MySQL connection pool
+let pool;
+try {
+    const config = getConfigFromEnv();
+    console.error('[Setup] MySQL configuration:', {
+        host: config.host,
+        port: config.port,
+        user: config.user,
+        password: config.password ? '********' : '(not provided)',
+        database: config.database || '(default not set)'
+    });
+    pool = createConnectionPool(config);
+}
+catch (error) {
+    console.error('[Fatal] Failed to initialize MySQL connection:', error);
+    process.exit(1);
+}
+/**
+ * Create an MCP server with tools for MySQL database access
+ */
+const server = new Server({
+    name: "mysql-mcp-server",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+/**
+ * Handler that lists available tools for MySQL database access
+ */
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "list_databases",
+                description: "List all accessible databases on the MySQL server",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: []
+                }
+            },
+            {
+                name: "list_tables",
+                description: "List all tables in a specified database",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        database: {
+                            type: "string",
+                            description: "Database name (optional, uses default if not specified)"
+                        }
+                    },
+                    required: []
+                }
+            },
+            {
+                name: "describe_table",
+                description: "Show the schema for a specific table",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        database: {
+                            type: "string",
+                            description: "Database name (optional, uses default if not specified)"
+                        },
+                        table: {
+                            type: "string",
+                            description: "Table name"
+                        }
+                    },
+                    required: ["table"]
+                }
+            },
+            {
+                name: "execute_query",
+                description: "Execute a read-only SQL query",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: {
+                            type: "string",
+                            description: "SQL query (only SELECT, SHOW, DESCRIBE, and EXPLAIN statements are allowed)"
+                        },
+                        database: {
+                            type: "string",
+                            description: "Database name (optional, uses default if not specified)"
+                        }
+                    },
+                    required: ["query"]
+                }
+            }
+        ]
+    };
+});
+/**
+ * Handler for MySQL database access tools
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+        switch (request.params.name) {
+            case "list_databases": {
+                console.error('[Tool] Executing list_databases');
+                const { rows } = await executeQuery(pool, 'SHOW DATABASES');
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify(rows, null, 2)
+                        }]
+                };
+            }
+            case "list_tables": {
+                console.error('[Tool] Executing list_tables');
+                const database = request.params.arguments?.database;
+                const { rows } = await executeQuery(pool, 'SHOW FULL TABLES', [], database);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify(rows, null, 2)
+                        }]
+                };
+            }
+            case "describe_table": {
+                console.error('[Tool] Executing describe_table');
+                const database = request.params.arguments?.database;
+                const table = request.params.arguments?.table;
+                if (!table) {
+                    throw new McpError(ErrorCode.InvalidParams, "Table name is required");
+                }
+                const { rows } = await executeQuery(pool, `DESCRIBE \`${table}\``, [], database);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify(rows, null, 2)
+                        }]
+                };
+            }
+            case "execute_query": {
+                console.error('[Tool] Executing execute_query');
+                const query = request.params.arguments?.query;
+                const database = request.params.arguments?.database;
+                if (!query) {
+                    throw new McpError(ErrorCode.InvalidParams, "Query is required");
+                }
+                // Validate that the query is read-only
+                validateQuery(query);
+                const { rows } = await executeQuery(pool, query, [], database);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify(rows, null, 2)
+                        }]
+                };
+            }
+            default:
+                throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
+        }
+    }
+    catch (error) {
+        console.error('[Error] Tool execution failed:', error);
+        // Format error message for client
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error: ${error instanceof Error ? error.message : String(error)}`
+                }],
+            isError: true
+        };
+    }
+});
+/**
+ * Start the server using stdio transport
+ */
+async function main() {
+    console.error('[Setup] Starting MySQL MCP server');
+    try {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        console.error('[Setup] MySQL MCP server running on stdio');
+    }
+    catch (error) {
+        console.error('[Fatal] Failed to start server:', error);
+        process.exit(1);
+    }
+}
+// Handle process termination
+process.on('SIGINT', async () => {
+    console.error('[Shutdown] Closing MySQL connection pool');
+    await pool.end();
+    process.exit(0);
+});
+// Start the server
+main().catch((error) => {
+    console.error('[Fatal] Unhandled error:', error);
+    process.exit(1);
+});

package/build/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for MySQL MCP server
+ */
+export {};

package/build/validators.js

@@ -0,0 +1,79 @@
+/**
+ * SQL query validators for MySQL MCP server
+ * Ensures that only read-only queries are allowed
+ */
+// List of allowed SQL commands (read-only operations)
+const ALLOWED_COMMANDS = [
+    'SELECT',
+    'SHOW',
+    'DESCRIBE',
+    'DESC',
+    'EXPLAIN',
+];
+// List of disallowed SQL commands (write operations)
+const DISALLOWED_COMMANDS = [
+    'INSERT',
+    'UPDATE',
+    'DELETE',
+    'DROP',
+    'CREATE',
+    'ALTER',
+    'TRUNCATE',
+    'RENAME',
+    'REPLACE',
+    'GRANT',
+    'REVOKE',
+    'LOCK',
+    'UNLOCK',
+    'CALL',
+    'EXEC',
+    'EXECUTE',
+    'SET',
+    'START',
+    'BEGIN',
+    'COMMIT',
+    'ROLLBACK',
+];
+/**
+ * Validates if a SQL query is read-only
+ * @param query SQL query to validate
+ * @returns true if the query is read-only, false otherwise
+ */
+export function isReadOnlyQuery(query) {
+    // Normalize query by removing comments and extra whitespace
+    const normalizedQuery = query
+        .replace(/--.*$/gm, '') // Remove single-line comments
+        .replace(/\/\*[\s\S]*?\*\//g, '') // Remove multi-line comments
+        .replace(/\s+/g, ' ') // Normalize whitespace
+        .trim()
+        .toUpperCase();
+    // Check if query starts with an allowed command
+    const startsWithAllowed = ALLOWED_COMMANDS.some(cmd => normalizedQuery.startsWith(cmd + ' ') || normalizedQuery === cmd);
+    // Check if query contains any disallowed commands
+    const containsDisallowed = DISALLOWED_COMMANDS.some(cmd => {
+        const regex = new RegExp(`(^|\\s)${cmd}(\\s|$)`);
+        return regex.test(normalizedQuery);
+    });
+    // Check for multiple statements (;)
+    const hasMultipleStatements = normalizedQuery.includes(';') &&
+        !normalizedQuery.endsWith(';');
+    // Query is read-only if it starts with an allowed command,
+    // doesn't contain any disallowed commands, and doesn't have multiple statements
+    return startsWithAllowed && !containsDisallowed && !hasMultipleStatements;
+}
+/**
+ * Validates if a SQL query is safe to execute
+ * @param query SQL query to validate
+ * @throws Error if the query is not safe
+ */
+export function validateQuery(query) {
+    console.error('[Validator] Validating query:', query);
+    if (!query || typeof query !== 'string') {
+        throw new Error('Query must be a non-empty string');
+    }
+    if (!isReadOnlyQuery(query)) {
+        console.error('[Validator] Query rejected: not read-only');
+        throw new Error('Only read-only queries are allowed (SELECT, SHOW, DESCRIBE, EXPLAIN)');
+    }
+    console.error('[Validator] Query validated as read-only');
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@cano721/mysql-mcp-server",
+  "version": "0.1.3",
+  "description": "An MCP server that provides read-only access to MySQL databases.",
+  "type": "module",
+  "bin": {
+    "mysql-mcp-server": "build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "inspector": "npx @modelcontextprotocol/inspector build/index.js",
+    "test:setup": "node test-setup.js",
+    "test:tools": "node test-tools.js",
+    "test": "npm run test:setup && npm run test:tools"
+  },
+  "keywords": [
+    "mcp",
+    "mysql",
+    "database",
+    "model-context-protocol",
+    "ai",
+    "llm"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cano721/mysql-mcp-server.git"
+  },
+  "author": "cano721",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "0.6.0",
+    "mysql2": "^3.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "dotenv": "^16.4.7",
+    "typescript": "^5.3.3"
+  }
+}