mysql-query-mcp-server

MySQL Query MCP Server

A Model Context Protocol (MCP) server that provides read-only MySQL database queries for AI assistants. Execute queries, explore database structures, and investigate your data directly from your AI-powered tools.

Supported AI Tools

This MCP server works with any tool that supports the Model Context Protocol, including:

• Cursor IDE: Set up in .cursor/mcp.json
• Anthropic Claude: Use with a compatible MCP client
• Other MCP-compatible AI assistants: Follow the tool's MCP configuration instructions

Features & Limitations

What It Does

• ✅ Execute read-only MySQL queries (SELECT, SHOW, DESCRIBE only)
• ✅ Work with predefined environments (local, development, staging, production)
• ✅ Provide database information and metadata
• ✅ List available database environments
• ✅ Support SSL connections for secure database access
• ✅ Implement query timeouts to prevent long-running operations

What It Doesn't Do

• ❌ Execute write operations (INSERT, UPDATE, DELETE, CREATE, ALTER, etc.)
• ❌ Support custom environment names (limited to local, development, staging, production)
• ❌ Provide database design or schema generation capabilities
• ❌ Function as a full database management tool

This tool is designed specifically for data investigation and exploration through read-only queries. It is not intended for database administration, schema management, or data modification.

Quick Install

# Install globally with npm
npm install -g mysql-query-mcp-server

# Or run directly with npx
npx mysql-query-mcp-server

Setup Instructions

Configure Your AI Tool to Use the MCP Server

Create or edit your MCP configuration file (e.g., .cursor/mcp.json for Cursor IDE):

Basic Configuration:

{
  "mysql": {
    "name": "MySQL Query MCP",
    "description": "MySQL read-only query access through MCP",
    "type": "bin", 
    "enabled": true,
    "bin": "mysql-query-mcp"
  }
}

Comprehensive Configuration with Database Credentials:

{
  "mysql": {
    "command": "npx",
    "args": ["mysql-query-mcp-server@latest"],
    "env": {
      "LOCAL_DB_HOST": "localhost",
      "LOCAL_DB_USER": "root",
      "LOCAL_DB_PASS": "<YOUR_LOCAL_DB_PASSWORD>",
      "LOCAL_DB_NAME": "your_database",
      "LOCAL_DB_PORT": "3306",
      
      "DEVELOPMENT_DB_HOST": "dev.example.com",
      "DEVELOPMENT_DB_USER": "<DEV_USER>",
      "DEVELOPMENT_DB_PASS": "<DEV_PASSWORD>",
      "DEVELOPMENT_DB_NAME": "your_database",
      "DEVELOPMENT_DB_PORT": "3306",
      
      "STAGING_DB_HOST": "staging.example.com",
      "STAGING_DB_USER": "<STAGING_USER>",
      "STAGING_DB_PASS": "<STAGING_PASSWORD>",
      "STAGING_DB_NAME": "your_database",
      "STAGING_DB_PORT": "3306",
      
      "PRODUCTION_DB_HOST": "prod.example.com",
      "PRODUCTION_DB_USER": "<PRODUCTION_USER>",
      "PRODUCTION_DB_PASS": "<PRODUCTION_PASSWORD>",
      "PRODUCTION_DB_NAME": "your_database",
      "PRODUCTION_DB_PORT": "3306",
      
      "DEBUG": "false",
      "MCP_MYSQL_SSL": "true",
      "MCP_MYSQL_REJECT_UNAUTHORIZED": "false"
    }
  }
}

Choosing the Right Configuration Approach

There are two ways to configure the MySQL MCP server:

• Binary Configuration (type: "bin", bin: "mysql-query-mcp")

  • When to use: When you've installed the package globally (npm install -g mysql-query-mcp-server)
  • Pros: Simpler configuration
  • Cons: Requires global installation

• Command Configuration (command: "npx", args: ["mysql-query-mcp-server@latest"])

  • When to use: When you want to use the latest version without installing it globally
  • Pros: No global installation required, all configuration in one file
  • Cons: More complex configuration

Choose the approach that best fits your workflow. Both methods will work correctly with any AI assistant that supports MCP.

Important Configuration Notes

• You must use the full environment names: LOCAL_, DEVELOPMENT_, STAGING_, PRODUCTION_
• Abbreviations like DEV_ or PROD_ will not work
• Global settings like DEBUG, MCP_MYSQL_SSL apply to all environments
• At least one environment (typically "local") must be configured
• You only need to configure the environments you plan to use
• For security reasons, consider using environment variables or secure credential storage for production credentials

Configuration Options

Environment Variable	Description	Default
DEBUG	Enable debug logging	false
[ENV]_DB_HOST	Database host for environment	-
[ENV]_DB_USER	Database username	-
[ENV]_DB_PASS	Database password	-
[ENV]_DB_NAME	Database name	-
[ENV]_DB_PORT	Database port	3306
[ENV]_DB_SSL	Enable SSL connection	false
MCP_MYSQL_SSL	Enable SSL for all connections	false
MCP_MYSQL_REJECT_UNAUTHORIZED	Verify SSL certificates	true

Integration with AI Assistants

Your AI assistant can interact with MySQL databases through the MCP server. Here are some examples:

Example queries:

Can you use the query tool to show me the first 10 users from the database? Use the local environment.

I need to analyze our sales data. Can you run a SQL query to get the total sales per region for last month from the development database?

Can you use the info tool to check what tables are available in the staging database?

Can you list all the available database environments we have configured?

Using MySQL MCP Tools

The MySQL Query MCP server provides three main tools that your AI assistant can use:

1. query

Execute read-only SQL queries against a specific environment:

Use the query tool to run:
SELECT * FROM customers WHERE signup_date > '2023-01-01' LIMIT 10;
on the development environment

2. info

Get detailed information about your database:

Use the info tool to check the status of our production database.

3. environments

List all configured environments from your configuration:

Use the environments tool to show me which database environments are available.

Available Tools

The MySQL Query MCP server provides three main tools:

1. query

Execute read-only SQL queries:

-- Example query to run with the query tool
SELECT * FROM users LIMIT 10;

Supported query types (strictly limited to):

• SELECT statements
• SHOW commands
• DESCRIBE/DESC tables

2. info

Get detailed information about your database:

• Server version
• Connection status
• Database variables
• Process list
• Available databases

3. environments

List all configured environments from your configuration:

Use the environments tool to show me which database environments are available.

Security Considerations

• ✅ Only read-only queries are allowed (SELECT, SHOW, DESCRIBE)
• ✅ Each environment has its own isolated connection pool
• ✅ SSL connections are supported for production environments
• ✅ Query timeouts prevent runaway operations
• ⚠️ Consider using secure credential management for database credentials

Troubleshooting

Connection Issues

If you're having trouble connecting:

• Verify your database credentials in your MCP configuration
• Ensure the MySQL server is running and accessible
• Check for firewall rules blocking connections
• Enable debug mode by setting DEBUG=true in your configuration

Common Errors

Error: No connection pool available for environment

• Make sure you've defined all required environment variables for that environment
• Check that you're using one of the supported environment names (local, development, staging, production)

Error: Query execution failed

• Verify your SQL syntax
• Check that you're only using supported query types (SELECT, SHOW, DESCRIBE)
• Ensure your query is truly read-only

For more comprehensive troubleshooting, see the Troubleshooting Guide.

For examples of how to integrate with AI assistants, see the Integration Examples.

For implementation details about the MCP protocol, see the MCP README.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

CI/CD and Release Process

This project uses GitHub Actions for continuous integration and automated releases.

CI/CD Workflow

The CI/CD pipeline consists of:

• Build and Test: Runs on every push to main and develop branches, and on pull requests to these branches

  • Tests the codebase with Node.js 16.x and 18.x
  • Ensures the package builds correctly
  • Validates all tests pass

• Release: Runs when changes are pushed to the main branch and the build/test job succeeds

  • Uses release-please to manage version bumps and changelog updates
  • Creates a release PR with version changes based on conventional commits
  • Automatically publishes to npm when a release PR is merged

Release Process

The project follows Semantic Versioning:

• Major version: Breaking changes (non-backward compatible)
• Minor version: New features (backward compatible)
• Patch version: Bug fixes and minor improvements

Commits should follow the Conventional Commits format:

• feat: add new feature - Minor version bump
• fix: resolve bug - Patch version bump
• docs: update documentation - No version bump
• chore: update dependencies - No version bump
• BREAKING CHANGE: change API - Major version bump

When you push to main, release-please will analyze commits and automatically create or update a release PR with appropriate version bumps and changelog entries.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Abou Koné - Engineering Leader and CTO

For more information or support, please open an issue on the GitHub repository.

Changelog

1.2.0 (2025-04-13)

Features

• enhance logging and debug information in MCP server initialization and tool handling (60fa45c)

Bug Fixes

• correct release-please output parameter name in workflow (4697cc9)
• update token reference in CI workflow to use GITHUB_TOKEN (b5b2ed3)

Miscellaneous

• add configuration files for CI/CD and npm publishing (0bfc3c9)
• Fix package.json format (99e5280)
• update .gitignore and add MCP_README for Model Context Protocol documentation (e77f01f)
• update CI workflow permissions for better access control (453f2b6)
• update dependencies and add vitest configuration for testing (8cda7b7)
• update package-lock.json for mysql-query-mcp-server (d0b8117)

Documentation

• Add npm and license badges to README (f076267)
• add troubleshooting guide and MCP implementation details to documentation (b55c08a)
• clarify .env file location requirements (843b56d)
• improve documentation and bump version to 1.1.0 (4ca8b85)
• improve README with clearer MCP configuration guidance (214eae2)
• remove .env approach and focus on MCP configuration (0610295)