read mysql.com
read mysql.com logo

Read MySQL

Secure read-only MySQL database access to execute queries and analyze data patterns.

Created byApr 22, 2025

MCP Server for MySQL based on NodeJS

![smithery badge](https://smithery.ai/badge/@benborla29/mcp-server-mysql)
Demo
A Model Context Protocol server that provides access to MySQL databases. This server enables LLMs to inspect database schemas and execute SQL queries.

Table of Contents

  • Requirements
  • Installation
  • Components
  • Configuration
  • Environment Variables
  • Multi-DB Mode
  • Schema-Specific Permissions
  • Testing
  • Troubleshooting
  • Contributing
  • License

Requirements

  • Node.js v18 or higher
  • MySQL 5.7 or higher (MySQL 8.0+ recommended)
  • MySQL user with appropriate permissions for the operations you need
  • For write operations: MySQL user with INSERT, UPDATE, and/or DELETE privileges

Installation

There are several ways to install and configure the MCP server:

Claude Desktop

To manually configure the MCP server for Claude Desktop App, add the following to your claude_desktop_config.json file (typically located in your user directory):

Cursor

For Cursor IDE, you can install this MCP server with the following command in your project:
Don't forget to replace the env values on that command. If you have the latest version (for v0.47 and above) of Cursor, just copy and paste the config below:
mcp.json

Using Smithery

The easiest way to install and configure this MCP server is through Smithery:
During configuration, you'll be prompted to enter your MySQL connection details. Smithery will automatically:
  • Set up the correct environment variables
  • Configure your LLM application to use the MCP server
  • Test the connection to your MySQL database
  • Provide helpful troubleshooting if needed
  • Configure write operation settings (INSERT, UPDATE, DELETE permissions)
The installation will ask for the following connection details:
  • MySQL Host (default: 127.0.0.1)
  • MySQL Port (default: 3306)
  • MySQL Username
  • MySQL Password
  • MySQL Database name
  • SSL Configuration (if needed)
  • Write operations permissions:
For security reasons, write operations are disabled by default. Enable them only if you need Claude to modify your database data.

Using MCP Get

You can also install this package using MCP Get:
MCP Get provides a centralized registry of MCP servers and simplifies the installation process.

Using NPM/PNPM

For manual installation:
After manual installation, you'll need to configure your LLM application to use the MCP server (see Configuration section below).

Running from Local Repository

If you want to clone and run this MCP server directly from the source code, follow these steps:
  1. Clone the repository
  1. Install dependencies
  1. Build the project
  1. Configure Claude DesktopAdd the following to your Claude Desktop configuration file (claude_desktop_config.json):Replace:
  1. Test the serverIf it connects to MySQL successfully, you're ready to use it with Claude Desktop.

Components

Tools

  • mysql_query

Resources

The server provides comprehensive database information:
  • Table Schemas

Security Features

  • SQL injection prevention through prepared statements
  • Query whitelisting/blacklisting capabilities
  • Rate limiting for query execution
  • Query complexity analysis
  • Configurable connection encryption
  • Read-only transaction enforcement

Performance Optimizations

  • Optimized connection pooling
  • Query result caching
  • Large result set streaming
  • Query execution plan analysis
  • Configurable query timeouts

Monitoring and Debugging

  • Comprehensive query logging
  • Performance metrics collection
  • Error tracking and reporting
  • Health check endpoints
  • Query execution statistics

Configuration

Automatic Configuration with Smithery

If you installed using Smithery, your configuration is already set up. You can view or modify it with:
When reconfiguring, you can update any of the MySQL connection details as well as the write operation settings:
  • Basic connection settings:
  • Write operation permissions:
For security reasons, all write operations are disabled by default. Only enable these settings if you specifically need Claude to modify your database data.

Advanced Configuration Options

For more control over the MCP server's behavior, you can use these advanced configuration options:

Environment Variables

Basic Connection

  • MYSQL_HOST: MySQL server host (default: "127.0.0.1")
  • MYSQL_PORT: MySQL server port (default: "3306")
  • MYSQL_USER: MySQL username (default: "root")
  • MYSQL_PASS: MySQL password
  • MYSQL_DB: Target database name (leave empty for multi-DB mode)

Performance Configuration

  • MYSQL_POOL_SIZE: Connection pool size (default: "10")
  • MYSQL_QUERY_TIMEOUT: Query timeout in milliseconds (default: "30000")
  • MYSQL_CACHE_TTL: Cache time-to-live in milliseconds (default: "60000")

Security Configuration

  • MYSQL_RATE_LIMIT: Maximum queries per minute (default: "100")
  • MYSQL_MAX_QUERY_COMPLEXITY: Maximum query complexity score (default: "1000")
  • MYSQL_SSL: Enable SSL/TLS encryption (default: "false")
  • ALLOW_INSERT_OPERATION: Enable INSERT operations (default: "false")
  • ALLOW_UPDATE_OPERATION: Enable UPDATE operations (default: "false")
  • ALLOW_DELETE_OPERATION: Enable DELETE operations (default: "false")
  • ALLOW_DDL_OPERATION: Enable DDL operations (default: "false")
  • SCHEMA_INSERT_PERMISSIONS: Schema-specific INSERT permissions
  • SCHEMA_UPDATE_PERMISSIONS: Schema-specific UPDATE permissions
  • SCHEMA_DELETE_PERMISSIONS: Schema-specific DELETE permissions
  • SCHEMA_DDL_PERMISSIONS: Schema-specific DDL permissions
  • MULTI_DB_WRITE_MODE: Enable write operations in multi-DB mode (default: "false")

Monitoring Configuration

  • MYSQL_ENABLE_LOGGING: Enable query logging (default: "false")
  • MYSQL_LOG_LEVEL: Logging level (default: "info")
  • MYSQL_METRICS_ENABLED: Enable performance metrics (default: "false")

Multi-DB Mode

MCP-Server-MySQL supports connecting to multiple databases when no specific database is set. This allows the LLM to query any database the MySQL user has access to. For full details, see README-MULTI-DB.md.

Enabling Multi-DB Mode

To enable multi-DB mode, simply leave the MYSQL_DB environment variable empty. In multi-DB mode, queries require schema qualification:

Schema-Specific Permissions

For fine-grained control over database operations, MCP-Server-MySQL now supports schema-specific permissions. This allows different databases to have different levels of access (read-only, read-write, etc.).

Configuration Example

For complete details and security recommendations, see README-MULTI-DB.md.

Testing

Database Setup

Before running tests, you need to set up the test database and seed it with test data:
  1. Create Test Database and User
  1. Run Database Setup ScriptThis will create the necessary tables and seed data. The script is located in scripts/setup-test-db.ts
  1. Configure Test Environment Create a .env.test file in the project root (if not existing):
  1. Update package.json Scripts Add these scripts to your package.json:

Running Tests

The project includes a comprehensive test suite to ensure functionality and reliability:

Troubleshooting

Common Issues

  1. Connection Issues
  1. Performance Issues
  1. Security Restrictions
  1. Path Resolution If you encounter an error "Could not connect to MCP server mcp-server-mysql", explicitly set the path of all required binaries:
Where can I find my `node` bin path Run the following command to get it:
For PATH
For NODE_PATH
  1. Claude Desktop Specific Issues
  1. Authentication Issues
  1. I am encountering Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv' imported from error try this workaround:
Thanks to @lizhuangs

Contributing

Contributions are welcome! Please feel free to submit a Pull Request to https://github.com/benborla/mcp-server-mysql

Development Setup

  1. Clone the repository
  1. Install dependencies: pnpm install
  1. Build the project: pnpm run build
  1. Run tests: pnpm test

Project Roadmap

We're actively working on enhancing this MCP server. Check our CHANGELOG.md for details on planned features, including:
  • Enhanced query capabilities with prepared statements
  • Advanced security features
  • Performance optimizations
  • Comprehensive monitoring
  • Expanded schema information
If you'd like to contribute to any of these areas, please check the issues on GitHub or open a new one to discuss your ideas.

Submitting Changes

  1. Fork the repository
  1. Create a feature branch: git checkout -b feature/your-feature-name
  1. Commit your changes: git commit -am 'Add some feature'
  1. Push to the branch: git push origin feature/your-feature-name
  1. Submit a pull request

License

This MCP server is licensed under the MIT License. See the LICENSE file for details.

MCP Server for MySQL based on NodeJS

![smithery badge](https://smithery.ai/badge/@benborla29/mcp-server-mysql)
Demo
A Model Context Protocol server that provides access to MySQL databases. This server enables LLMs to inspect database schemas and execute SQL queries.

Table of Contents

  • Requirements
  • Installation
  • Components
  • Configuration
  • Environment Variables
  • Multi-DB Mode
  • Schema-Specific Permissions
  • Testing
  • Troubleshooting
  • Contributing
  • License

Requirements

  • Node.js v18 or higher
  • MySQL 5.7 or higher (MySQL 8.0+ recommended)
  • MySQL user with appropriate permissions for the operations you need
  • For write operations: MySQL user with INSERT, UPDATE, and/or DELETE privileges

Installation

There are several ways to install and configure the MCP server:

Claude Desktop

To manually configure the MCP server for Claude Desktop App, add the following to your claude_desktop_config.json file (typically located in your user directory):

Cursor

For Cursor IDE, you can install this MCP server with the following command in your project:
Don't forget to replace the env values on that command. If you have the latest version (for v0.47 and above) of Cursor, just copy and paste the config below:
mcp.json

Using Smithery

The easiest way to install and configure this MCP server is through Smithery:
During configuration, you'll be prompted to enter your MySQL connection details. Smithery will automatically:
  • Set up the correct environment variables
  • Configure your LLM application to use the MCP server
  • Test the connection to your MySQL database
  • Provide helpful troubleshooting if needed
  • Configure write operation settings (INSERT, UPDATE, DELETE permissions)
The installation will ask for the following connection details:
  • MySQL Host (default: 127.0.0.1)
  • MySQL Port (default: 3306)
  • MySQL Username
  • MySQL Password
  • MySQL Database name
  • SSL Configuration (if needed)
  • Write operations permissions:
For security reasons, write operations are disabled by default. Enable them only if you need Claude to modify your database data.

Using MCP Get

You can also install this package using MCP Get:
MCP Get provides a centralized registry of MCP servers and simplifies the installation process.

Using NPM/PNPM

For manual installation:
After manual installation, you'll need to configure your LLM application to use the MCP server (see Configuration section below).

Running from Local Repository

If you want to clone and run this MCP server directly from the source code, follow these steps:
  1. Clone the repository
  1. Install dependencies
  1. Build the project
  1. Configure Claude DesktopAdd the following to your Claude Desktop configuration file (claude_desktop_config.json):Replace:
  1. Test the serverIf it connects to MySQL successfully, you're ready to use it with Claude Desktop.

Components

Tools

  • mysql_query

Resources

The server provides comprehensive database information:
  • Table Schemas

Security Features

  • SQL injection prevention through prepared statements
  • Query whitelisting/blacklisting capabilities
  • Rate limiting for query execution
  • Query complexity analysis
  • Configurable connection encryption
  • Read-only transaction enforcement

Performance Optimizations

  • Optimized connection pooling
  • Query result caching
  • Large result set streaming
  • Query execution plan analysis
  • Configurable query timeouts

Monitoring and Debugging

  • Comprehensive query logging
  • Performance metrics collection
  • Error tracking and reporting
  • Health check endpoints
  • Query execution statistics

Configuration

Automatic Configuration with Smithery

If you installed using Smithery, your configuration is already set up. You can view or modify it with:
When reconfiguring, you can update any of the MySQL connection details as well as the write operation settings:
  • Basic connection settings:
  • Write operation permissions:
For security reasons, all write operations are disabled by default. Only enable these settings if you specifically need Claude to modify your database data.

Advanced Configuration Options

For more control over the MCP server's behavior, you can use these advanced configuration options:

Environment Variables

Basic Connection

  • MYSQL_HOST: MySQL server host (default: "127.0.0.1")
  • MYSQL_PORT: MySQL server port (default: "3306")
  • MYSQL_USER: MySQL username (default: "root")
  • MYSQL_PASS: MySQL password
  • MYSQL_DB: Target database name (leave empty for multi-DB mode)

Performance Configuration

  • MYSQL_POOL_SIZE: Connection pool size (default: "10")
  • MYSQL_QUERY_TIMEOUT: Query timeout in milliseconds (default: "30000")
  • MYSQL_CACHE_TTL: Cache time-to-live in milliseconds (default: "60000")

Security Configuration

  • MYSQL_RATE_LIMIT: Maximum queries per minute (default: "100")
  • MYSQL_MAX_QUERY_COMPLEXITY: Maximum query complexity score (default: "1000")
  • MYSQL_SSL: Enable SSL/TLS encryption (default: "false")
  • ALLOW_INSERT_OPERATION: Enable INSERT operations (default: "false")
  • ALLOW_UPDATE_OPERATION: Enable UPDATE operations (default: "false")
  • ALLOW_DELETE_OPERATION: Enable DELETE operations (default: "false")
  • ALLOW_DDL_OPERATION: Enable DDL operations (default: "false")
  • SCHEMA_INSERT_PERMISSIONS: Schema-specific INSERT permissions
  • SCHEMA_UPDATE_PERMISSIONS: Schema-specific UPDATE permissions
  • SCHEMA_DELETE_PERMISSIONS: Schema-specific DELETE permissions
  • SCHEMA_DDL_PERMISSIONS: Schema-specific DDL permissions
  • MULTI_DB_WRITE_MODE: Enable write operations in multi-DB mode (default: "false")

Monitoring Configuration

  • MYSQL_ENABLE_LOGGING: Enable query logging (default: "false")
  • MYSQL_LOG_LEVEL: Logging level (default: "info")
  • MYSQL_METRICS_ENABLED: Enable performance metrics (default: "false")

Multi-DB Mode

MCP-Server-MySQL supports connecting to multiple databases when no specific database is set. This allows the LLM to query any database the MySQL user has access to. For full details, see README-MULTI-DB.md.

Enabling Multi-DB Mode

To enable multi-DB mode, simply leave the MYSQL_DB environment variable empty. In multi-DB mode, queries require schema qualification:

Schema-Specific Permissions

For fine-grained control over database operations, MCP-Server-MySQL now supports schema-specific permissions. This allows different databases to have different levels of access (read-only, read-write, etc.).

Configuration Example

For complete details and security recommendations, see README-MULTI-DB.md.

Testing

Database Setup

Before running tests, you need to set up the test database and seed it with test data:
  1. Create Test Database and User
  1. Run Database Setup ScriptThis will create the necessary tables and seed data. The script is located in scripts/setup-test-db.ts
  1. Configure Test Environment Create a .env.test file in the project root (if not existing):
  1. Update package.json Scripts Add these scripts to your package.json:

Running Tests

The project includes a comprehensive test suite to ensure functionality and reliability:

Troubleshooting

Common Issues

  1. Connection Issues
  1. Performance Issues
  1. Security Restrictions
  1. Path Resolution If you encounter an error "Could not connect to MCP server mcp-server-mysql", explicitly set the path of all required binaries:
Where can I find my `node` bin path Run the following command to get it:
For PATH
For NODE_PATH
  1. Claude Desktop Specific Issues
  1. Authentication Issues
  1. I am encountering Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv' imported from error try this workaround:
Thanks to @lizhuangs

Contributing

Contributions are welcome! Please feel free to submit a Pull Request to https://github.com/benborla/mcp-server-mysql

Development Setup

  1. Clone the repository
  1. Install dependencies: pnpm install
  1. Build the project: pnpm run build
  1. Run tests: pnpm test

Project Roadmap

We're actively working on enhancing this MCP server. Check our CHANGELOG.md for details on planned features, including:
  • Enhanced query capabilities with prepared statements
  • Advanced security features
  • Performance optimizations
  • Comprehensive monitoring
  • Expanded schema information
If you'd like to contribute to any of these areas, please check the issues on GitHub or open a new one to discuss your ideas.

Submitting Changes

  1. Fork the repository
  1. Create a feature branch: git checkout -b feature/your-feature-name
  1. Commit your changes: git commit -am 'Add some feature'
  1. Push to the branch: git push origin feature/your-feature-name
  1. Submit a pull request

License

This MCP server is licensed under the MIT License. See the LICENSE file for details.

Related servers

magicslides
magicslides logo

MagicSlides MCP Server

A server that implements the Model Context Protocol (MCP) to generate PowerPoint presentations from text, YouTube videos, or structured JSON data.

A server that implements the Model Context Protocol (MCP) to generate PowerPoint presentations from text, YouTube videos, or structured JSON data.

Bitrefill
Bitrefill logo

Bitrefill

Integrates with Bitrefill's platform to search and retrieve information about gift cards, mobile refills, eSIMs, and dig...

Integrates with Bitrefill's platform to search and retrieve information about gift cards, mobile refills, eSIMs, and dig...

OEvortex
OEvortex logo

DuckDuckGo Search

Provides web search capabilities through DuckDuckGo, enabling content retrieval, URL processing, and metadata extraction...

Provides web search capabilities through DuckDuckGo, enabling content retrieval, URL processing, and metadata extraction...

Iaptic
Iaptic logo

Iaptic

Integrates with Iaptic's customer and transaction data to enable querying, analysis, and insights for e-commerce and cus...

Integrates with Iaptic's customer and transaction data to enable querying, analysis, and insights for e-commerce and cus...