lzc-mysql-mcp

library2.0.0jsnpmunverified

A read-only MCP (Model Context Protocol) server for querying MySQL databases via stdio transport, supporting multi-database connections, custom table hints, and automatic LIMIT/timeout enforcement. Current stable version is 2.0.0. It is published on npm and can be run immediately with npx without cloning or building. Key differentiators include zero-install usage, multi-source configuration via a single JSON file, table description prompts for AI awareness, and strict read-only enforcement at the protocol level (only SELECT/SHOW/DESCRIBE/EXPLAIN allowed). Uses mysql2 connection pools (max 5 concurrent) and formats results as Markdown tables. Designed for integration with Claude Code, OpenAI Codex, Claude Desktop, Cursor, and Windsurf. Published under MIT license.

database ai-ml

npm install lzc-mysql-mcp

package ↗

INSTALL

IMPORT

SIG · LZC-MYSQL-MCP

lzc-mysql-mcp

databasejavascriptv2.0.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.

MySqlMcpServer (CLI tool)

✓ npx lzc-mysql-mcp

✗ npm install -g lzc-mysql-mcp && lzc-mysql-mcp

Package is designed for npx usage; global install is not recommended. No programmatic API is exposed.

setupServer (internal)

✓ import { setupServer } from 'lzc-mysql-mcp/src/index.js'

✗ const { setupServer } = require('lzc-mysql-mcp')

This is an internal function not documented for external use. ESM-only; no CommonJS export. May change without notice.

config types (TypeScript)

✓ import type { Config, ConnectionConfig } from 'lzc-mysql-mcp/dist/types.js'

✗ import { Config } from 'lzc-mysql-mcp'

TypeScript types are shipped under dist/types.js. Named exports available for Config and ConnectionConfig interfaces. Do not import from the main entry point.

Shows minimal setup: create JSON config, run npx lzc-mysql-mcp, and integrate with an MCP-compatible AI client.

// Step 1: Create configuration file ~/.mysql-mcp/config.json // { // "defaultDatabase": "big_market", // "maxRows": 1000, // "queryTimeout": 30000, // "connections": [ // { // "host": "127.0.0.1", // "port": 3306, // "user": "root", // "password": "password123", // "database": "big_market", // "description": "Core business database" // } // ] // } // Step 2: Run server npx lzc-mysql-mcp // Output: // [mysql-mcp] 使用配置文件: /Users/user/.mysql-mcp/config.json // [mysql-mcp] 已连接 MySQL 8.0.x @ 127.0.0.1:3306, 数据库: big_market // [mysql-mcp] 共 1 个数据源已就绪, 默认数据库: big_market // [mysql-mcp] Server 已启动 (stdio 模式) // Step 3: Configure AI client (e.g., Claude Desktop) to use the server // In claude_desktop_config.json: // { // "mcpServers": { // "mysql": { // "command": "npx", // "args": ["lzc-mysql-mcp"] // } // } // }

Debug

Known issues

gotchaSELECT queries without LIMIT will automatically have LIMIT 1000 appended (configurable via maxRows). This can cause unexpected truncated results.

fix

Always explicitly specify a LIMIT clause if you need a specific number of rows; otherwise be aware the default limit applies.

affects: >=2.0.0

gotchaConfiguration file must be named exactly mysql-config.json (project-level) or config.json (global). Other names will not be found.

fix

Use one of the supported file names or set MYSQL_CONFIG_FILE environment variable to the full path.

affects: >=2.0.0

gotchaThe package does not support CommonJS require(). Using require() will throw an error.

fix

Use npx (CLI) or dynamic import() if you need to use programmatically.

affects: >=2.0.0

gotchaDatabase names must be globally unique across all connections in the configuration file. Duplicate database names will cause undefined behavior.

fix

Ensure each connection's database field is unique across the entire config.

affects: >=2.0.0

gotchaThe server runs in stdio mode only; there is no HTTP or WebSocket transport. It must be launched as a subprocess by the MCP client.

fix

Configure your AI client (e.g., Claude Desktop) to spawn the server as a subprocess using npx lzc-mysql-mcp.

affects: >=2.0.0

deprecatedEnvironment variable single-database mode (MYSQL_HOST, MYSQL_PORT, etc.) is considered legacy and may be removed in future versions. Multi-database JSON config is recommended.

fix

Migrate to mysql-config.json or ~/.mysql-mcp/config.json for persistent configuration.

affects: >=2.0.0

gotchaPassword in config file is stored in plaintext. No encryption or obfuscation is provided.

fix

Ensure the config file has restrictive permissions (e.g., chmod 600 on Unix). Consider using environment variables or a secrets manager for production.

affects: >=2.0.0

Errors

Common errors & fixes

npx: command not found: lzc-mysql-mcp

The package is not yet published or the npm registry is not accessible.

fix

Ensure you have internet access and npm is configured correctly. Run: npm install -g lzc-mysql-mcp@latest (but prefer npx).

[mysql-mcp] 未找到配置文件, 请创建 mysql-config.json 或设置 MYSQL_DATABASE 环境变量

Server could not find any valid configuration. None of the search paths (./mysql-config.json, ~/.mysql-mcp/config.json, environment variables) were present.

fix

Create one of the supported configuration files or set the required environment variables. See README for details.

Error: ER_ACCESS_DENIED_ERROR: Access denied for user 'root'@'localhost' (using password: YES)

Incorrect MySQL username or password in the configuration.

fix

Verify the credentials in the config file. For testing, use a user with SELECT privileges only.

Error: Cannot find module 'mysql2'

The mysql2 package is missing. This should be installed automatically by npm when running via npx, but may fail if npm is misconfigured.

fix

Run: npx lzc-mysql-mcp (it will install dependencies automatically). If that fails, manually install: npm install -g lzc-mysql-mcp.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

mysql2requiredMySQL database driver for connection pooling and query execution

@modelcontextprotocol/sdkrequiredMCP SDK for stdio server transport and tool registration

Agent activity

10 hits · last 30 days

node

Resources

packagelzc-mysql-mcp ↗