mysql-mcp-x

library1.0.1jsnpmunverified

A Model Context Protocol (MCP) server for MySQL, designed to integrate AI assistants like Claude Desktop, Cursor, Cline, and Windsurf with MySQL 8+ databases. Version 1.0.1 provides tools for safe SQL querying, transactional execution, and schema inspection. It automatically connects on startup using environment variables, uses a connection pool via mysql2 with auto-reconnect, enforces SQL safety by blocking DROP/TRUNCATE/ALTER operations, requiring WHERE clauses for UPDATE/DELETE, limiting queries to 200 rows, and wrapping writes in transactions. Ships TypeScript types. Requires Node >=20.0.0.

database ai-ml

npm install mysql-mcp-x

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MYSQL-MCP-X

mysql-mcp-x

databasejavascriptv1.0.1

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.

main entry

✓ npx mysql-mcp-x

✗ import mysqlMcpX from 'mysql-mcp-x'

mysql-mcp-x is not a library; it's a CLI/server. Run via npx or configure as an MCP server in your AI client's config.

server binary

✓ import { MCPMySQL } from 'mysql-mcp-x'

✗ import mysqlMcpX from 'mysql-mcp-x'

No JavaScript import exists; the package only exports a CLI binary. Use the MCP config to invoke it.

development import

✓ import { run } from 'tsx'; run('mysql-mcp-x')

✗ require('mysql-mcp-x')

In development, use `tsx` to run the TypeScript source directly. The package does not expose a require-able module.

Shows how to configure mysql-mcp-x as an MCP server in Claude Desktop with environment variables for database connection.

// Configure in Claude Desktop config (claude_desktop_config.json): { "mcpServers": { "mysql-mcp-x": { "command": "npx", "args": ["-y", "mysql-mcp-x"], "env": { "MYSQL_HOST": "127.0.0.1", "MYSQL_PORT": "3306", "MYSQL_USER": "root", "MYSQL_PASSWORD": process.env.MYSQL_PASSWORD ?? '', "MYSQL_DATABASE": "mydb" } } } } // Then in Claude Desktop, use tools: query, execute, schema. // Example query: SELECT * FROM users LIMIT 5;

Debug

Known issues

breakingRequires Node.js >=20.0.0

fix

Upgrade Node.js to v20 or later.

affects: <20.0.0

gotchaquery tool automatically adds LIMIT 200; may return fewer rows than expected

fix

Specify LIMIT in your SQL to override the default.

affects: >=1.0.0

gotchaexecute tool wraps every statement in a transaction; DDL statements (e.g., CREATE TABLE) may cause implicit commit and break rollback

fix

Use execute only for DML (INSERT/UPDATE/DELETE); for DDL, use a direct MySQL client.

affects: >=1.0.0

deprecatedNo explicit connect_db tool – connection is automatic via env vars

fix

Set environment variables (MYSQL_HOST, MYSQL_USER, etc.) before starting the server.

affects: >=1.0.0

breakingDROP, TRUNCATE, and ALTER statements are blocked by default

fix

Use a MySQL client (e.g., mysql CLI) to execute such commands.

affects: >=1.0.0

gotchaUPDATE and DELETE require a WHERE clause; otherwise the tool returns an error

fix

Always include a WHERE clause in UPDATE/DELETE statements.

affects: >=1.0.0

Errors

Common errors & fixes

npx mysql-mcp-x: command not found

The package is not installed globally or npx cache issue.

fix

Run 'npx -y mysql-mcp-x' or install globally with 'npm install -g mysql-mcp-x'

Error: ER_NOT_SUPPORTED_AUTH_MODE: Client does not support authentication protocol requested by server

MySQL server uses caching_sha2_password but mysql2 may need encryption adjustments.

fix

Ensure Node >=20 and mysql2 is up-to-date; alternatively, alter MySQL user to mysql_native_password (not recommended).

Error: SQL execution blocked: DROP/TRUNCATE/ALTER not allowed

The server blocks destructive DDL commands for safety.

fix

Use a direct MySQL client to execute these statements.

Error: UPDATE/DELETE without WHERE clause is not allowed

Safety check prevents mass modifications.

fix

Add a WHERE clause to your UPDATE or DELETE statement.

Error: Cannot find module 'mysql-mcp-x'

The package is imported as a module instead of run via CLI.

fix

Use 'npx mysql-mcp-x' or the MCP server configuration instead of importing.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkrequiredRequired to implement the MCP protocol for server-tool communication with AI clients.

mysql2requiredMySQL client for Node.js, provides connection pooling and authentication support for caching_sha2_password.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/lr-liang/mysql-mcp-x ↗

packagemysql-mcp-x ↗

homepagehttps://github.com/lr-liang/mysql-mcp-x#readme ↗