apaezespinosa/mcp-server-mysql

MCP Server for MySQL

A Model Context Protocol (MCP) server that provides seamless connectivity and operations for MySQL databases. This server allows AI assistants to interact with MySQL databases through a standardized protocol.

🎯 Quick Setup

Need help? Jump to IDE Integration for detailed instructions.

Table of Contents

• Features
• Installation
• Quick Start
  • For Cursor Users
  • For VS Code Users
  • For Other IDEs
• Usage
• IDE Integration
  • Cursor IDE
  • Visual Studio Code
  • Other IDEs
• Configuration
• Development
• Troubleshooting
• Contributing

Features

• Database Connection Management: Secure connection handling with configurable parameters
• SQL Query Execution: Execute SELECT, INSERT, UPDATE, DELETE, and other SQL operations
• Schema Exploration: Discover database structure, tables, columns, indexes, and constraints
• Table Information: Get detailed information about table schemas and relationships
• Database Listing: List available databases and tables
• Error Handling: Comprehensive error handling with detailed error messages
• Connection Pooling: Efficient connection management for better performance
• SSL Support: Secure connections with SSL/TLS encryption

Installation

Prerequisites

• Node.js 18+
• MySQL server 5.7+ or MySQL 8.0+
• npm or yarn package manager

Setup

Option 1: Quick Install (Recommended)

git clone <repository-url>
cd mcp-server-mysql
./install.sh

Option 2: Manual Setup

1. Clone or download this repository

   git clone <repository-url>
   cd mcp-server-mysql
   

2. Install dependencies

   npm install
   

3. Configure environment variables

   cp .env.example .env
   

   Edit .env file with your MySQL connection details:

   MYSQL_HOST=localhost
   MYSQL_PORT=3306
   MYSQL_USER=your_username
   MYSQL_PASSWORD=your_password
   MYSQL_DATABASE=your_database
   MYSQL_SSL=false
   

4. Build the project

   npm run build
   

Quick Start

For Cursor Users

1. Clone this repository
2. Run npm install && npm run build
3. Copy cursor-mcp-config.json to your Cursor config directory
4. Update the MySQL connection details in the config
5. Restart Cursor and start chatting with your database!

For VS Code Users

1. Clone this repository
2. Run npm install && npm run build
3. Install the MCP extension from VS Code marketplace
4. Update .vscode/settings.json with your MySQL credentials
5. Press F5 to debug or use the provided tasks

For Other IDEs

1. Follow the installation steps below
2. Use the generic MCP client configuration
3. Configure your IDE according to the specific instructions

🚀 IDE Integration

Important: This MCP server works with multiple IDEs! See the detailed IDE Integration section below for step-by-step instructions for your preferred editor.

Supported IDEs:

• ✅ Cursor (Built-in MCP support)
• ✅ Visual Studio Code (with MCP extension)
• ✅ IntelliJ IDEA / WebStorm
• ✅ Sublime Text
• ✅ Vim/Neovim
• ✅ Any MCP-compatible client

Usage

Running the Server

Development mode:

npm run dev

Production mode:

npm start

Watch mode (auto-restart on changes):

npm run watch

Available Tools

The MCP server provides the following tools for MySQL operations:

1. mysql_query

Execute SQL queries on the MySQL database.

Parameters:

• query (string): The SQL query to execute
• database (string, optional): Specific database to query (overrides default)

Example:

{
  "name": "mysql_query",
  "arguments": {
    "query": "SELECT * FROM users WHERE age > 25",
    "database": "myapp"
  }
}

2. mysql_list_databases

List all available databases on the MySQL server.

Example:

{
  "name": "mysql_list_databases",
  "arguments": {}
}

3. mysql_list_tables

List all tables in a specific database.

Parameters:

• database (string, optional): Database name (uses default if not specified)

Example:

{
  "name": "mysql_list_tables",
  "arguments": {
    "database": "myapp"
  }
}

4. mysql_describe_table

Get detailed information about a table's structure.

Parameters:

• table (string): Table name
• database (string, optional): Database name (uses default if not specified)

Example:

{
  "name": "mysql_describe_table",
  "arguments": {
    "table": "users",
    "database": "myapp"
  }
}

5. mysql_get_schema

Get comprehensive schema information for a database.

Parameters:

• database (string, optional): Database name (uses default if not specified)

Example:

{
  "name": "mysql_get_schema",
  "arguments": {
    "database": "myapp"
  }
}

IDE Integration

Cursor IDE

Cursor has built-in MCP support. Follow these steps to integrate the MySQL MCP server:

1. Install the project dependencies:

   npm install
   npm run build
   

2. Configure Cursor MCP settings:

   • Open Cursor settings (Cmd/Ctrl + ,)
   • Search for "MCP" or navigate to Extensions → MCP
   • Add the following configuration to your MCP settings:

   {
     "mcpServers": {
       "mysql": {
         "command": "node",
         "args": ["/absolute/path/to/mcp-server-mysql/dist/index.js"],
         "env": {
           "MYSQL_HOST": "localhost",
           "MYSQL_PORT": "3306",
           "MYSQL_USER": "your_username",
           "MYSQL_PASSWORD": "your_password",
           "MYSQL_DATABASE": "your_database"
         }
       }
     }
   }
   

3. Alternative: Use the provided config file:

   • Copy cursor-mcp-config.json to your Cursor configuration directory
   • Update the paths and environment variables as needed
   • Restart Cursor

4. Test the connection:

   • Open a new chat in Cursor
   • Try asking: "List all databases in my MySQL server"
   • The MCP server should respond with database information

Visual Studio Code

VS Code requires the MCP extension to work with MCP servers:

1. Install the MCP extension:

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

2. Configure MCP settings:

   • Open VS Code settings (Cmd/Ctrl + ,)
   • Search for "MCP"
   • Add the server configuration:

   {
     "mcp.servers": {
       "mysql": {
         "command": "node",
         "args": ["${workspaceFolder}/dist/index.js"],
         "env": {
           "MYSQL_HOST": "localhost",
           "MYSQL_PORT": "3306",
           "MYSQL_USER": "your_username",
           "MYSQL_PASSWORD": "your_password",
           "MYSQL_DATABASE": "your_database"
         }
       }
     }
   }
   

3. Use the provided VS Code configuration:

   • The project includes .vscode/settings.json with pre-configured MCP settings
   • Update the environment variables in the settings file
   • Reload VS Code window (Cmd/Ctrl + Shift + P → "Developer: Reload Window")

4. Debug the MCP server:

   • Use the provided launch configurations in .vscode/launch.json
   • Set breakpoints in your code
   • Press F5 to start debugging

Other IDEs

IntelliJ IDEA / WebStorm

1. Install Node.js plugin (if not already installed)

2. Configure MCP server as external tool:

   • Go to File → Settings → Tools → External Tools
   • Add new tool with:
     • Name: MCP MySQL Server
     • Program: node
     • Arguments: dist/index.js
     • Working directory: $ProjectFileDir$
     • Environment variables: Add your MySQL connection details

3. Create run configuration:

   • Go to Run → Edit Configurations
   • Add new Node.js configuration
   • Set JavaScript file to dist/index.js
   • Add environment variables for MySQL connection

Sublime Text

1. Install LSP-MCP package:

   • Install Package Control if not already installed
   • Install "LSP-MCP" package

2. Configure LSP settings:

   • Open Preferences → Package Settings → LSP → Settings
   • Add MCP server configuration:

   {
     "clients": {
       "mcp-mysql": {
         "command": ["node", "/path/to/mcp-server-mysql/dist/index.js"],
         "env": {
           "MYSQL_HOST": "localhost",
           "MYSQL_PORT": "3306",
           "MYSQL_USER": "your_username",
           "MYSQL_PASSWORD": "your_password",
           "MYSQL_DATABASE": "your_database"
         }
       }
     }
   }
   

Vim/Neovim

1. Install MCP plugin:

   " Using vim-plug
   Plug 'modelcontextprotocol/mcp-vim'
   

2. Configure in your vimrc:

   let g:mcp_servers = {
     \ 'mysql': {
     \   'command': 'node',
     \   'args': ['/path/to/mcp-server-mysql/dist/index.js'],
     \   'env': {
     \     'MYSQL_HOST': 'localhost',
     \     'MYSQL_PORT': '3306',
     \     'MYSQL_USER': 'your_username',
     \     'MYSQL_PASSWORD': 'your_password',
     \     'MYSQL_DATABASE': 'your_database'
     \   }
     \ }
     \ }
   

Generic MCP Client Configuration

For any MCP-compatible client, use this configuration:

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-mysql/dist/index.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Configuration

Environment Variables

Security Considerations

• Never commit .env files to version control
• Use strong passwords for MySQL users
• Enable SSL in production environments
• Consider using connection pooling for high-traffic applications
• Implement proper user permissions in MySQL

Development

Project Structure

mcp-server-mysql/
├── src/
│   ├── index.ts          # Main server entry point
│   ├── config.ts         # Configuration management
│   ├── types.ts          # TypeScript type definitions
│   ├── connection.ts     # MySQL connection management
│   └── tools/            # MCP tool implementations
│       ├── query.ts      # SQL query execution
│       ├── schema.ts     # Schema exploration
│       └── database.ts   # Database operations
├── dist/                 # Compiled JavaScript output
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .env.example          # Environment variables template
└── README.md            # This file

Building from Source

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Run in development mode
npm run dev

Testing

To test the server, you can use any MCP-compatible client or test the tools directly:

# Test database connection
npm run dev

Troubleshooting

IDE-Specific Issues

Cursor IDE:

• MCP Server Not Found: Ensure the path to dist/index.js is absolute
• Connection Timeout: Check if the server is running and accessible
• Permission Denied: Verify Node.js permissions and file access rights

VS Code:

• Extension Not Working: Ensure MCP extension is properly installed and enabled
• Debug Not Starting: Check launch.json configuration and Node.js path
• Tasks Not Running: Verify tasks.json syntax and npm script availability

IntelliJ IDEA:

• External Tool Fails: Check Node.js installation and PATH configuration
• Run Configuration Error: Verify JavaScript file path and environment variables
• Plugin Conflicts: Disable conflicting database plugins if issues occur

Common Issues

1. Connection Refused

   • Verify MySQL server is running
   • Check host and port configuration
   • Ensure firewall allows connections

2. Authentication Failed

   • Verify username and password
   • Check MySQL user permissions
   • Ensure user can connect from the specified host

3. Database Not Found

   • Verify database name in configuration
   • Ensure database exists on MySQL server
   • Check user has access to the database

4. SSL Connection Issues

   • Verify SSL configuration
   • Check certificate validity
   • Ensure MySQL server supports SSL

5. IDE Integration Issues

   • Path Problems: Use absolute paths in IDE configurations
   • Environment Variables: Ensure all required env vars are set
   • Node.js Version: Verify Node.js 18+ is installed and accessible
   • Build Issues: Run npm run build before starting the server

Logs and Debugging

Enable debug logging by setting environment variables:

DEBUG=mcp:* npm run dev

IDE-Specific Debugging:

VS Code:

• Use the provided launch configurations
• Set breakpoints in TypeScript source files
• View debug console for detailed output

Cursor:

• Check Cursor's developer console (Help → Toggle Developer Tools)
• Monitor network requests in the Network tab
• Use browser dev tools for debugging

IntelliJ IDEA:

• Use the built-in debugger with Node.js run configurations
• Set breakpoints and inspect variables
• View console output in the Run tool window

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Create an issue in the repository
• Check the troubleshooting section
• Review MySQL documentation for database-specific issues