MySQL

This MCP server provides a standardized way to interact with a MySQL database through the Model Context Protocol, enabling you to connect to a database, run queries, and manage data via a consistent MCP API. It exposes common database actions through a simple, tool-based interface that you can call from any MCP-compliant client.

How to use

You can use this server with an MCP client to connect to a MySQL database, run SELECT queries, insert or modify data, and inspect tables. The tools are designed to be invoked through the MCP API, so you can integrate database operations into your workflows or applications without writing direct database clients.

• connect_db: Establish a connection to the MySQL database using your credentials
• query: Run SELECT statements with optional prepared parameters
• execute: Run INSERT, UPDATE, or DELETE statements with optional prepared parameters
• list_tables: Retrieve all tables in the connected database
• describe_table: Get the schema of a specific table

How to install

Prerequisites: you should have Python 3.11 or higher, a MySQL server running, and Docker installed if you plan to use containerized deployment.

# Installing via Smithery (recommended for automatic setup)

npx -y @smithery/cli install @aqaranewbiz/mysql-aqaranewbiz --client claude

# Manual installation (local run)
npx @aqaranewbiz/mysql-aqaranewbiz

# Environment variables (for MCP configuration)
"MYSQL_HOST": "your_host",
"MYSQL_USER": "your_user",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "your_database"

Configuration and startup

Configure the MCP server connection using the following MCP settings. This defines a local MCP stdio server named mysql that runs via npx and passes the required environment variables.

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@aqaranewbiz/mysql-aqaranewbiz"],
      "env": {
        "MYSQL_HOST": "your_host",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Starting locally

Set up a Python virtual environment and install dependencies, then run the server locally. You can also build and run a Docker container if you prefer containerized deployment.

# Local installation (recommended)

# Windows
python -m venv venv
venv\Scripts\activate

# macOS/Linux
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the server
python mcp_server.py

Docker installation

If you want to run the server in Docker, build the image and run a container with the required environment variables.

docker build -t mysql-mcp-server .

# Run the container with MySQL connection details
docker run -e MYSQL_HOST=host -e MYSQL_USER=user -e MYSQL_PASSWORD=pass -e MYSQL_DATABASE=db mysql-mcp-server

API endpoints and usage patterns

The server exposes endpoints to retrieve server status and to execute queries. You can fetch server status and available tools, or send a query through the execute endpoint to perform database operations.

GET /status  // Returns server status and available tools
POST /execute // Executes a MySQL query and returns results

Security and best practices

Keep your database credentials secure. Use strong passwords, rotate credentials regularly, and limit user privileges to what is strictly needed for your MCP operations. When running in Docker, avoid exposing your database host or credentials publicly and prefer network-restricted access.

Troubleshooting

If you encounter connection issues, verify that the MySQL server is reachable and that the environment variables are correctly set. For query errors, check the SQL syntax, database permissions, and ensure the correct database is selected.

If logs are needed, you can run the server with a higher log level to gather more information.

Development notes

Tools exposed by this server are designed to be called via an MCP client. You can extend functionality by adding more tools to mcp_server.py and updating tests accordingly.

Available tools

connect_db

Establish a connection to the MySQL database using provided credentials.

query

Execute SELECT queries with optional prepared statement parameters and return results.

execute

Execute INSERT, UPDATE, or DELETE queries with optional prepared statement parameters.

list_tables

List all tables in the connected database.

describe_table

Get the structure of a specific table.