LLM-Native MySQL Interaction Engine (MCP Compliant)

This utility serves as a bridge, enabling Large Language Models (LLMs) to issue SQL commands against locally hosted MySQL or MariaDB relational databases. Communication adheres strictly to the Model Context Protocol (MCP) using stdin/stdout pipes, eliminating the need for any TCP/IP port listeners on the server side.

Prerequisites

• Runtime Environment: Node.js version 20.0.0 or newer.
• Database: MySQL version 5.7+ or MariaDB server.

Core Capabilities

• SQL Command Dispatch: Execute arbitrary SQL statements dictated by the LLM.
• Schema Discovery: Retrieve listings of available databases, tables within a schema, and detailed table structure definitions.
• MCP Adherence: Fully compliant with the Model Context Protocol structure for seamless LLM integration.
• I/O Channeling: Relies exclusively on standard input and output channels for bidirectional messaging; no socket setup required.
• Credential Vault: Maintains and allows dynamic switching between multiple stored connection configurations using mnemonic profile names.
• Persistent Settings: Persists connection parameters locally for rapid reconnection and profile reuse.

Quick Start and Invocation

Ephemeral Execution via NPX

 npx -y https://github.com/yuki777/mysql-mcp-server --host 127.0.0.1 --port 13306 --user root

Parameterization Guide

Flag	Purpose	Default Value
-h, --host <address>	MySQL server hostname	localhost
-p, --port <number>	MySQL listener port	13306
-u, --user <username>	Authentication user ID	root
--password <secret>	Authentication secret string	(Empty)
-d, --database <schema>	Target schema name upon connection	(Optional)
-c, --config <path>	Path to an external configuration file	(Optional)
--auto-connect	Attempt database linkage upon initiation	false
--server-port <port>	MCP socket port (Irrelevant for stdio mode)	3000
--server-host <address>	MCP socket host (Irrelevant for stdio mode)	localhost
--query-timeout <ms>	Maximum allowable duration for query execution (milliseconds)	30000
--max-results <count>	Ceiling on the number of returned rows per query	1000
--debug	Verbose diagnostic output mode	false

Connection Profile Persistence and Retrieval

The MySQL MCP Server automatically serializes successfully established database credentials into named profiles stored locally. This permits invoking the server later and specifying a connection purely by its assigned profile moniker. These profile records are safeguarded within a JSON file (.mysql-mcp-connections.json) located in the user's home directory.

Each stored credential set encompasses: - Profile Identifier - Hostname/IP - Port Number - Credential User - Access Secret - Designated Schema (if specified)

This system enables granular orchestration of access across diverse database environments via simple naming conventions.

Configuration File Utilization

Connection parameters can alternatively be supplied via a JSON structure in a specified file:

{
  "server": {
    "port": 3000,
    "host": "localhost"
  },
  "mysql": {
    "host": "localhost",
    "port": 13306,
    "user": "root",
    "password": "yourpassword",
    "database": "mydb"
  },
  "debug": false,
  "queryTimeout": 30000,
  "maxResultSize": 1000
}

To invoke using a configuration file:

npx -y https://github.com/yuki777/mysql-mcp-server -c ./mysql-mcp-config.json

Communication Protocol

The server operates in MCP 'stdio' mode, ensuring all transactional data exchange occurs through the standard input and output streams, bypassing local network binding entirely. Key advantages of this methodology include:

1. Conflict Avoidance: Eliminates reliance on specific port allocations, preventing resource conflicts.
2. Enhanced Security Posture: Reduced network attack surface as no external ports are opened.
3. Streamlined IPC: Simplifies the inter-process communication pathway between the LLM runtime and the database interface.

Operational Notes

• Communication messages are strictly structured as JSON objects.
• Each distinct JSON entity must occupy a single line in the stream.
• Diagnostic output, including connection events and errors, is routed exclusively to standard error (stderr).

Exposed MCP Toolkit Functions

Connection Lifecycle Management

Function Name	Role	Mandatory Arguments
connect_database	Establishes a novel database link	host, port, user
connect_by_profile	Initiates linkage using a saved profile identifier	profileName
disconnect_database	Terminates the active database session	None
get_connection_status	Queries the current linkage state	None

Profile Repository Operations

Function Name	Role	Mandatory Arguments
list_profiles	Fetches a registry of all stored profiles	None
get_profile	Retrieves detailed parameters for a specific profile	profileName
add_profile	Registers a new connection configuration	profileName, host, port, user
remove_profile	Deletes an existing profile entry	profileName

Data Querying Utilities

Function Name	Role	Mandatory Arguments
execute_query	Executes a provided SQL statement	query: SQL String
get_databases	Lists all accessible database schemas	None
get_tables	Lists tables within a specified schema	database (Optional)
describe_table	Retrieves the schema definition (columns, types) for a table	table

Decoupled Connection Workflow

MySQL MCP Server permits the separation of the engine's initialization from the initial database connection attempt. This separation confers significant operational flexibility:

1. Server Launch Without Credentials: The process starts independently of any database configuration.
2. Dynamic Reconfiguration: Allows the server to pivot between connections to different databases post-launch.
3. Zero-Dependency Startup: Achievable via the simplest invocation: npx -y https://github.com/yuki777/mysql-mcp-server

Workflow Illustration

1. Initialize Engine (No Auto-Connect): bash npx -y https://github.com/yuki777/mysql-mcp-server

2. Establish Connection & Save Profile: (Sent via stdin to the running process) json { "type": "tool_call", "request_id": "req_1", "tool": "connect_database", "arguments": { "host": "localhost", "port": 3306, "user": "root", "password": "your_password", "database": "your_db", "profileName": "my-db" } }

3. Query Stored Profiles: (Sent via stdin) json { "type": "tool_call", "request_id": "req_2", "tool": "list_profiles", "arguments": {} }

4. Connect Using Stored Alias: (Sent via stdin) json { "type": "tool_call", "request_id": "req_3", "tool": "connect_by_profile", "arguments": { "profileName": "my-db" } }

5. Archive New Profile Definition (Without Connecting): json { "type": "tool_call", "request_id": "req_4", "tool": "add_profile", "arguments": { "profileName": "production-db", "host": "prod.example.com", "port": 3306, "user": "prod_user", "password": "prod_password", "database": "production" } }

6. Verify Active Linkage: (Sent via stdin) json { "type": "tool_call", "request_id": "req_5", "tool": "get_connection_status", "arguments": {} }

7. Close Session: (Sent via stdin) json { "type": "tool_call", "request_id": "req_6", "tool": "disconnect_database", "arguments": {} }

Testing Suite

A dedicated Node.js script, test-connection-management.js, is provided within the source repository to facilitate validation of the connection management features.

node test-connection-management.js

Developer Information

Environment Setup

# Clone the repository source
git clone [repository-url]
cd mysql-mcp-server

# Install required NPM packages
npm install

# Execute in development mode
npm run dev

Build Artifact Generation

npm run build

Licensing

ISC License

Contributions

Feedback, issue reports, feature suggestions, and merge requests are highly encouraged and welcomed.