Content
# MySQL MCP Server
The MySQL Model Context Protocol (MCP) server is a tool that connects to a local MySQL database, allowing large language models (LLM) to execute SQL queries.
## Requirements
- **Node.js**: Version 20.0.0 or higher
- **MySQL**: MySQL or MariaDB server version 5.7 or higher
## Features
- **Execute MySQL Queries**: Directly execute SQL queries from LLM
- **Retrieve Database Information**: Get a list of databases, tables, and check table structures
- **MCP Compliance**: Supports Model Context Protocol and can be integrated with LLM
- **stdio Communication**: Communicates with LLM using standard input/output without port binding
- **Save Connection Information**: Saves database connection information locally for reuse
## Installation and Usage
### Temporary Execution with NPX
```bash
npx -y https://github.com/yuki777/mysql-mcp-server --host 127.0.0.1 --port 13306 --user root
```
### Options
| Option | Description | Default Value |
|--------|-------------|---------------|
| `-h, --host <host>` | MySQL host | localhost |
| `-p, --port <port>` | MySQL port | 13306 |
| `-u, --user <user>` | MySQL user | root |
| `--password <password>` | MySQL password | (empty string) |
| `-d, --database <database>` | Default database | (optional) |
| `-c, --config <path>` | Configuration file path | (optional) |
| `--auto-connect` | Automatically connect to the database on server startup | false |
| `--server-port <port>` | MCP server port (not used in stdio mode) | 3000 |
| `--server-host <host>` | MCP server host (not used in stdio mode) | localhost |
| `--query-timeout <ms>` | Query timeout (milliseconds) | 30000 |
| `--max-results <count>` | Maximum number of result rows | 1000 |
| `--debug` | Debug mode | false |
### Saving and Reusing Connection Information
The MySQL MCP Server saves the information of successfully connected databases locally. This allows for automatic reuse of connection information during the next startup. The saved connection information is stored in the `.mysql-mcp-connections.json` file located in the user's home directory.
The connection information includes:
- Hostname
- Port number
- Username
- Password
- Database name (if set)
### Using a Configuration File
You can also set connection information using a configuration file (in JSON format):
```json
{
"server": {
"port": 3000,
"host": "localhost"
},
"mysql": {
"host": "localhost",
"port": 13306,
"user": "root",
"password": "yourpassword",
"database": "mydb"
},
"debug": false,
"queryTimeout": 30000,
"maxResultSize": 1000
}
```
When using a configuration file:
```bash
npx -y https://github.com/yuki777/mysql-mcp-server -c ./mysql-mcp-config.json
```
## Communication Method
The MySQL MCP Server operates in "stdio" mode compliant with MCP (Model Context Protocol). This allows communication without binding to a specific port, using standard input/output instead. The advantages include:
1. **Avoiding Port Conflicts**: No specific port is used, eliminating port conflict issues.
2. **Enhanced Security**: By not using network communication, the risk of network-level attacks is reduced.
3. **Simplified Inter-Process Communication**: Communication with LLM is simplified.
### Notes
- In stdio mode, JSON-formatted messages are exchanged.
- One JSON message must be sent per line.
- Error information and connection logs are output to standard error (stderr).
## Provided MCP Tools
### Database Connection Management
| Tool Name | Description | Required Parameters |
|-----------|-------------|---------------------|
| connect_database | Connects to the database | host, port, user |
| disconnect_database | Disconnects the current database connection | None |
| get_connection_status | Retrieves the status of the database connection | None |
### SQL Query Operations
| Tool Name | Description | Required Parameters |
|-----------|-------------|---------------------|
| execute_query | Executes a MySQL query | query: SQL statement |
| get_databases | Retrieves a list of available databases | None |
| get_tables | Retrieves a list of tables in the specified database | database (optional) |
| describe_table | Retrieves the structure of the specified table | table |
## Connection Management Features
The MySQL MCP Server allows separation of server startup and database connection. This approach offers the following benefits:
1. **Startup Without Connection Information**: The server can start without database connection information.
2. **Switching Connections to Multiple Databases**: After server startup, it is possible to switch connections to different databases.
3. **Simple Installation**: Can be executed with just `npx -y https://github.com/yuki777/mysql-mcp-server`.
### How to Use Connection Management
1. **Start the server without auto-connection**:
```bash
npx -y https://github.com/yuki777/mysql-mcp-server
```
2. **Use the connection tool to connect to the database**:
```json
{
"type": "tool_call",
"request_id": "req_1",
"tool": "connect_database",
"arguments": {
"host": "localhost",
"port": 3306,
"user": "root",
"password": "your_password",
"database": "your_db"
}
}
```
3. **Check connection status**:
```json
{
"type": "tool_call",
"request_id": "req_2",
"tool": "get_connection_status",
"arguments": {}
}
```
4. **Disconnect**:
```json
{
"type": "tool_call",
"request_id": "req_3",
"tool": "disconnect_database",
"arguments": {}
}
```
### Test Script
The repository includes a test script named `test-connection-management.js`. You can use this script to test the connection management features:
```bash
node test-connection-management.js
```
## Developer Information
### Setting Up the Development Environment
```bash
# Clone the repository
git clone [repository-url]
cd mysql-mcp-server
# Install dependencies
npm install
# Run in development mode
npm run dev
```
### Build
```bash
npm run build
```
## License
ISC
## Contribution
Bug reports, feature requests, and pull requests are welcome.
