gvishnoi/mysql-server-mcp

MySQL Model Context Protocol Server

This project implements a Model Context Protocol (MCP) server that exposes MySQL database operations as tools. It wraps a MySQL connection pool and translates incoming MCP requests into SQL statements, returning results or errors in a structured format.

The server is written in plain JavaScript and uses the @modelcontextprotocol/sdk package to implement the MCP specification. The code is organized so that it can be developed and debugged from either Visual Studio Code or IntelliJ IDEA. It relies on environment variables to configure the database connection and exposes a set of tools for read‐only queries, table creation, data insertion, updates, deletions and general SQL statements.

Getting Started

1. Install dependencies using your preferred package manager. For example, using npm:

   npm install
   

2. Configure your MySQL connection via environment variables or by creating a .env file. The following variables are recognized:

   Variable	Default	Description
   MYSQL_HOST	localhost	Hostname of the MySQL server
   MYSQL_PORT	3306	Port of the MySQL server
   MYSQL_USER	username	Username used to authenticate
   MYSQL_PASSWORD	password	Password used to authenticate
   MYSQL_DATABASE	database_name	Default database for queries

3. Start the server by running:

   npm start
   

The server communicates over stdio, which is the default transport for MCP. When integrated with a larger application, the MCP runtime will spawn this process and handle the I/O channel automatically.

Supported Tools

The server exposes six tools, each corresponding to a different class of SQL statements:

Each tool accepts a single argument, query, which is the SQL statement to run. The server performs basic validation to ensure that statements are routed to the correct handler and prevents accidental misuse (for example, calling run_sql_query with a non‑SELECT statement).

Project Layout

mysql-server-mcp/
├── package.json      – project metadata and dependencies
├── .gitignore        – ignore common development artifacts
├── README.md         – this file
└── src
    └── index.js      – main entrypoint implementing the MCP server

The code is intentionally kept simple and self‑contained. You can run and debug it directly from either VS Code or IntelliJ by using their Node.js run configurations. The server uses modern ECMAScript modules, so be sure that your editor is configured accordingly.

How to Use This MCP Server in Local Environment

This MySQL MCP server can be integrated with various AI coding assistants and tools that support the Model Context Protocol. Below are detailed instructions for different environments.

Prerequisites

Before configuring any client, ensure:

1. MySQL Server is Running: Make sure your MySQL server is accessible

   # Test connection
   mysql -h localhost -u <username> -p<password> <database_name>
   

2. Dependencies Installed: Run npm install in the project directory

3. Server Path: Note the full path to your index.js file

   # Get the full path
   pwd  # Run this from the project root
   # Example: /Users/username/projects/mysql-server-mcp
   

Configuration for Claude Desktop

Claude Desktop natively supports MCP servers. To add this MySQL server:

1. Locate or Create Configuration File:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add Server Configuration:

   {
     "mcpServers": {
       "mysql-server": {
         "command": "node",
         "args": [
           "/absolute/path/to/mysql-server-mcp/src/index.js"
         ],
         "env": {
           "MYSQL_HOST": "localhost",
           "MYSQL_PORT": "3306",
           "MYSQL_USER": "username",
           "MYSQL_PASSWORD": "password",
           "MYSQL_DATABASE": "database_name"
         }
       }
     }
   }
   

3. Restart Claude Desktop: Close and reopen the application

4. Verify: The MySQL tools should appear in Claude's available tools list

Configuration for VS Code with GitHub Copilot

VS Code with GitHub Copilot can use MCP servers through the MCP extension:

1. Install MCP Extension (if not already installed):

   • Open VS Code
   • Go to Extensions (Cmd+Shift+X or Ctrl+Shift+X)
   • Search for "Model Context Protocol"
   • Install the official MCP extension

2. Configure MCP Server:

   • Option A: User Settings (applies to all workspaces)

     • Open Command Palette (Cmd+Shift+P or Ctrl+Shift+P)
     • Type "Preferences: Open User Settings (JSON)"
     • Add the following configuration:

     {
       "mcp.servers": {
         "mysql-server": {
           "command": "node",
           "args": [
             "/absolute/path/to/mysql-server-mcp/src/index.js"
           ],
           "env": {
             "MYSQL_HOST": "localhost",
             "MYSQL_PORT": "3306",
             "MYSQL_USER": "username",
             "MYSQL_PASSWORD": "password",
             "MYSQL_DATABASE": "database_name"
           }
         }
       }
     }
     

   • Option B: Workspace Settings (applies to current workspace only)

     • Create or edit .vscode/settings.json in your project
     • Add the same configuration as above

3. Reload VS Code: Run "Developer: Reload Window" from Command Palette

4. Usage with GitHub Copilot:

   • Open GitHub Copilot Chat (Cmd+I or Ctrl+I)
   • The MySQL MCP tools will be available for the AI to use
   • Example prompt: "Show me all tables in the database"

Configuration for Cline (formerly Claude Dev)

If you're using the Cline extension in VS Code:

1. Locate Cline MCP Settings:

   • On macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   • On Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
   • On Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

2. Add Server Configuration:

   {
     "mcpServers": {
       "mysql-server": {
         "command": "node",
         "args": [
           "/absolute/path/to/mysql-server-mcp/src/index.js"
         ],
         "env": {
           "MYSQL_HOST": "localhost",
           "MYSQL_PORT": "3306",
           "MYSQL_USER": "username",
           "MYSQL_PASSWORD": "password",
           "MYSQL_DATABASE": "database_name"
         }
       }
     }
   }
   

3. Restart Cline: Reload the VS Code window

Configuration for Other MCP-Compatible Clients

For any other tool that supports MCP via stdio transport:

1. Basic Command:

   node /path/to/mysql-server-mcp/src/index.js
   

2. With Environment Variables:

   MYSQL_HOST=localhost \
   MYSQL_PORT=3306 \
   MYSQL_USER=username \
   MYSQL_PASSWORD=password \
   MYSQL_DATABASE=database_name \
   node /path/to/mysql-server-mcp/src/index.js
   

3. Using .env File (create .env in project root):

   MYSQL_HOST=localhost
   MYSQL_PORT=3306
   MYSQL_USER=username
   MYSQL_PASSWORD=password
   MYSQL_DATABASE=database_name
   

Testing the MCP Server

You can test the server manually using the MCP Inspector:

1. Install MCP Inspector:

   npm install -g @modelcontextprotocol/inspector
   

2. Run Inspector:

   mcp-inspector node /path/to/mysql-server-mcp/src/index.js
   

3. Test Tools: The inspector provides a web UI to test all available tools

Troubleshooting

Server Won't Start:

• Check that Node.js is installed: node --version (requires v16+)
• Verify MySQL credentials are correct
• Check MySQL server is running and accessible

Tools Not Appearing:

• Verify the absolute path to index.js is correct
• Check configuration file syntax (valid JSON)
• Restart the client application completely
• Check client logs for connection errors

Connection Errors:

• Verify MySQL connection string and credentials
• Test MySQL connection independently: mysql -h localhost -u username -p
• Check firewall settings if using remote MySQL
• Ensure the database specified in config exists

Permission Errors:

• Ensure the MySQL user has appropriate permissions:

  GRANT ALL PRIVILEGES ON database_name.* TO 'username'@'localhost';
  FLUSH PRIVILEGES;
  

Security Considerations

For Production Use:

• Never commit credentials to version control
• Use environment variables or secure secret management
• Restrict MySQL user permissions to minimum required
• Consider using MySQL SSL/TLS connections
• Implement additional query validation and sanitization
• Add rate limiting and query timeouts
• Log all database operations for audit purposes

For Local Development:

• Use a dedicated development database
• Don't use production credentials
• Consider using Docker for isolated MySQL instances

Example Usage Scenarios

Once configured, you can interact with the AI assistant naturally:

Querying Data:

• "Show me all records from the users table"
• "Count how many orders were placed last month"
• "Find all products with price greater than $100"

Creating Tables:

• "Create a table called customers with id, name, and email columns"
• "Add a new table for storing product reviews"

Modifying Data:

• "Insert a new user with name and email"
• "Update the price of product ID"
• "Delete all orders older than 2 years"
• etc.

Schema Operations:

• "Add a created_at timestamp column to the users table"
• "Show me the structure of the orders table"
• "Create an index on the email column"

The AI assistant will automatically use the appropriate MCP tools to execute these operations and return the results.

Extending

If you wish to extend the server with additional functionality, consider adding new handlers and registering them in src/index.js. You can also modify the validation helpers to enforce stricter patterns or integrate with a query parser.