easy-mysql-mcp

library1.1.0jsnpmunverified

An MCP (Model Context Protocol) server that provides structured MySQL database tools for AI assistants. Version 1.1.0, actively maintained on GitHub. Built with TypeScript, official MCP SDK, and mysql2/promise. Features read-only queries, data modification, batch execution, CSV import/export, schema discovery, EXPLAIN support, user/permission checks, and policy enforcement (allow/deny tables, approval hooks). Configured via environment variables. Compatible with Claude Desktop, Codex, and OpenCode. Requires Node >=18. Differentiated by its comprehensive tool set, read-only mode, and external policy hook for AI safety.

database

npm install easy-mysql-mcp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EASY-MYSQL-MCP

easy-mysql-mcp

databasejavascriptv1.1.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.

Server

✓ import { Server } from '@modelcontextprotocol/sdk/server/index.js'

✗ import Server from '@modelcontextprotocol/sdk'

The MCP SDK exports named members; default import does not exist.

StdioServerTransport

✓ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

✗ import { StdioServerTransport } from '@modelcontextprotocol/sdk'

Subpath import required; not re-exported from top-level.

CallToolRequestSchema

✓ import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'

Type imports also available: import type { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'

Configure an MCP client to launch easy-mysql-mcp via npx and use its tools.

// In your MCP client config (e.g., Claude Desktop): { "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" } } } } // Then use MCP client to call tools: // mysql_query with query: "SELECT * FROM users" // mysql_execute with statement: "INSERT INTO users (name) VALUES (?)", params: ["Alice"] // mysql_import_csv with table: "users", csv content: "name,email\nBob,bob@example.com"

Debug

Known issues

gotchaWhen setting MYSQL_READ_ONLY=true, the mysql_execute tool is not registered; calling it will result in 'Tool not found'.

fix

Set MYSQL_READ_ONLY=false or omit it if you need write operations. Alternatively use MYSQL_MCP_MODE=readonly for the same effect.

affects: >=1.0.0

gotchaThe MYSQL_POLICY_HOOK URL must return a 200 or 202 for acceptance; non-2xx or timeout will reject the query.

fix

Ensure the policy endpoint is reachable and responds promptly. Set MYSQL_APPROVAL_TTL_SECONDS appropriately (default 300s).

affects: >=1.0.0

gotchaCSV import expects UTF-8 encoding; non-UTF-8 files may cause data corruption.

fix

Convert your CSV to UTF-8 before importing. The first row must contain column names matching the target table.

affects: >=1.0.0

deprecatedMYSQL_MCP_MODE=readonly is deprecated in favor of MYSQL_READ_ONLY=true. In a future version, MYSQL_MCP_MODE may be removed.

fix

Use MYSQL_READ_ONLY=true instead of MYSQL_MCP_MODE=readonly.

affects: >=1.1.0

gotchaConnection pool limits may cause 'ER_CON_COUNT_ERROR' if too many concurrent requests exceed pool size.

fix

Increase MYSQL_CONNECTION_LIMIT (default 10) or reduce concurrent tool calls. Pool exhaustion blocks further requests; set MYSQL_WAIT_FOR_CONNECTIONS=true to queue.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module '@modelcontextprotocol/sdk'

Missing peer dependency @modelcontextprotocol/sdk when installed outside npx context.

fix

Install the package locally: npm install @modelcontextprotocol/sdk

Error: getaddrinfo ENOTFOUND localhost

MYSQL_HOST environment variable is not set or set to an unreachable host.

fix

Set MYSQL_HOST to the correct MySQL hostname or IP. Example: MYSQL_HOST=127.0.0.1

Error: ER_ACCESS_DENIED_ERROR: Access denied for user 'root'@'localhost'

Invalid MySQL credentials in environment variables.

fix

Verify MYSQL_USER and MYSQL_PASSWORD. Use correct values and ensure the user has proper permissions.

Error: Unknown database 'your_database'

The specified MYSQL_DATABASE does not exist on the MySQL server.

fix

Create the database first, or change MYSQL_DATABASE to an existing database.

Error: connect ETIMEDOUT

MySQL server is not reachable due to network issues, firewall, or wrong port.

fix

Check MYSQL_HOST and MYSQL_PORT (default 3306). Ensure the MySQL server is running and accessible from the client.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

mysql2requiredMySQL database driver for connections and queries

@modelcontextprotocol/sdkrequiredMCP protocol implementation for server and tool registration

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/chenkumi/easy-mysql-mcp ↗

packageeasy-mysql-mcp ↗

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