mysql-mcp-toolkit

library1.2.0jsnpmunverified

MCP server for MySQL that enables Cursor and other MCP clients to interact with MySQL databases via config file or environment variables. Current stable version is 1.2.0. Release cadence is irregular. Key differentiators: read-only protection for production connections, full EXPLAIN support, server-side query timeout via MAX_EXECUTION_TIME hint, and automatic LIMIT on SELECT queries. Ships TypeScript types.

database devops

npm install mysql-mcp-toolkit

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MYSQL-MCP-TOOLKIT

mysql-mcp-toolkit

databasejavascriptv1.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

getConfig

✓ import { getConfig } from 'mysql-mcp-toolkit'

✗ const { getConfig } = require('mysql-mcp-toolkit')

Package is ESM-only since v1. CommonJS require will fail.

MySqlMCPServer

✓ import { MySqlMCPServer } from 'mysql-mcp-toolkit'

Class for programmatic use. Not exposed in the default CLI build.

main

✓ import { main } from 'mysql-mcp-toolkit'

✗ import main from 'mysql-mcp-toolkit'

main is a named export, not default.

Shows how to configure and run the MySQL MCP server with a config file and integrate with Cursor.

// Setup mysql-mcp-toolkit with environment variables // Run: npx -y mysql-mcp-toolkit --config /path/to/config.json // Example config.json: { "connections": [ { "name": "production", "host": "127.0.0.1", "port": 3306, "user": "root", "password": "secret", "database": "myapp", "readOnly": true } ] } // In Cursor's mcp.json: { "mcpServers": { "mysql": { "command": "npx", "args": ["-y", "mysql-mcp-toolkit", "--config", "/absolute/path/to/config.json"] } } } // All fields with 'your-' are treated as placeholders and rejected. // Max 10,000 rows returned per query. Server-side timeout via MAX_EXECUTION_TIME.

Debug

Known issues

breakingConfig file migration: v1.0.0 changed config format from .env to JSON. Old .env-based configs are ignored.

fix

Run `npx -y mysql-mcp-toolkit init` to generate the new JSON config and replace old credentials.

affects: <1.0.0

breakingESM-only: Since v1.0.0, the package ships as ESM and requires Node >= 18. CommonJS require() will fail.

fix

Use import syntax or dynamic import(). For CJS projects, use dynamic require with await import() or switch to ESM.

affects: >=1.0.0

gotchaPlaceholder detection: Any config field containing 'your-' is considered a placeholder and causes connection rejection at startup.

fix

Replace all placeholder values in the config file with actual credentials.

affects: >=1.0.0

gotchaRead-only mode: When MYSQL_READ_ONLY is 'true', INSERT/UPDATE/DELETE/DDL/CALL are rejected, including CTE-disguised writes.

fix

Set MYSQL_READ_ONLY to 'false' or omit to allow writes.

affects: >=0.5.0

gotchaIdentifier validation: describe_table, show_create_table require identifiers 1–64 chars, no backticks or control characters.

fix

Sanitize identifiers before passing them as arguments.

affects: >=1.0.0

deprecatedOld tool named 'run_sql' was renamed to 'execute_query' in v1.2.0. The old name still works but will be removed.

fix

Use 'execute_query' instead of 'run_sql'.

affects: 1.2.0

Errors

Common errors & fixes

Error: Config file contains placeholder values. Please replace all 'your-' values before running.

Config file has unset placeholder fields containing 'your-'.

fix

Edit config file and replace any field containing 'your-' with actual values.

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/mysql-mcp-toolkit from not supported.

Trying to require() the ESM package in a CommonJS project.

fix

Use import syntax or set type: 'module' in package.json.

Error: ER_PARSE_ERROR: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax near '?' …

Using named parameters instead of positional '?' placeholders.

fix

Use ? placeholders in SQL and pass parameters as an array in the 'params' option.

Error: Cannot perform write operation on a read-only connection.

MYSQL_READ_ONLY is true but client tried INSERT/UPDATE/DELETE/DDL/CALL.

fix

Set MYSQL_READ_ONLY to false or connect to a non-read-only connection.

Error: Table or view name 'my-table' is invalid (reason).

Identifier contains backticks or control characters; or length is <1 or >64.

fix

Use only alphanumeric characters, dollar signs, hyphens, and unicode letters. No backticks.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

mysql2requiredMySQL database driver

@modelcontextprotocol/sdkrequiredMCP server implementation

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/ogzhncrt/mysql-mcp ↗

packagemysql-mcp-toolkit ↗

homepagehttps://github.com/ogzhncrt/mysql-mcp#readme ↗