SQL Local MCP Server

A Model Context Protocol (MCP) server for executing SQL queries on MySQL databases. This allows Claude and other MCP-compatible AI assistants to connect to and interact with your local databases, particularly useful for DDEV containerized projects.

Features

• Dynamic Database Connections: Connect to any MySQL database by providing credentials directly to Claude
• READ-ONLY Security: Only SELECT, SHOW, DESCRIBE, and EXPLAIN queries are allowed - all destructive operations are blocked
• Multi-Statement Protection: Prevents SQL injection through semicolon-separated statements
• Database Exploration: List tables and describe table structures safely
• DDEV Compatible: Perfect for working with DDEV local development environments
• No Configuration Files: Database credentials are provided by Claude at runtime, not stored in config files

Installation

1. Clone or create the repository:

   cd sql-local-mcp

2. Create a virtual environment:

   python3 -m venv venv

3. Activate the virtual environment:

   • On macOS and Linux:

     source venv/bin/activate

   • On Windows:

     .\venv\Scripts\activate

4. Install dependencies:

   pip install -r requirements.txt

Usage with Claude

Starting the MCP Server

You can start the server using the provided script:

./start_server.sh

Or run directly:

python3 mcp_server.py

Connecting Claude to the MCP Server

For Claude Desktop

Add the following configuration to your Claude Desktop MCP settings file:

Location of config file:

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

Configuration:

{
  "mcpServers": {
    "sql-local-mcp": {
      "command": "/full/path/to/sql-local-mcp/start_server.sh",
      "args": []
    }
  }
}

Replace /full/path/to/sql-local-mcp/ with the actual path to your project directory.

Note: After updating the configuration, restart Claude Desktop.

Available Tools

The server provides the following tools:

Available Tools

1. connect_database - Connect to a MySQL database
2. execute_query - Execute SQL queries on connected databases
3. list_tables - List all tables in a database
4. describe_table - Get the structure of a specific table

Example Usage

Once Claude is connected to your MCP server, you can ask it to:

1. Connect to your DDEV database:

   "Connect to my DDEV database with these credentials:
   - host: 127.0.0.1
   - port: 32768 (or your DDEV MySQL port)
   - user: root
   - password: root
   - database: my_project_db
   - connection_name: ddev_project"
   

2. Explore the database:

   "List all tables in the ddev_project database"
   "Describe the structure of the users table"
   

3. Execute queries:

   "Show me the first 10 users from the users table"
   "Count how many orders were placed today"
   

Getting DDEV Database Connection Info

To get your DDEV database connection details:

ddev describe

Look for the "MySQL/MariaDB connection info" section. Typically:

• Host: 127.0.0.1
• Port: (varies, shown in ddev describe output)
• Username: root
• Password: root
• Database: Your project's database name

Security Notes

🔒 Read-Only Protection

• ONLY read-only queries are allowed: SELECT, SHOW, DESCRIBE (DESC), EXPLAIN
• All destructive operations are blocked: UPDATE, DELETE, INSERT, REPLACE, TRUNCATE, DROP, ALTER, CREATE, RENAME, GRANT, REVOKE, SET, USE, CALL, DO, HANDLER, LOAD, LOCK, UNLOCK
• Multi-statement protection: Queries with semicolons are blocked to prevent SQL injection
• Query validation happens before database connection for maximum security

🛡️ General Security

• Database credentials are provided at runtime by Claude and are not stored in configuration files
• Connections are maintained only during the session
• The server runs locally and is not exposed to the internet
• Parameterized queries are supported for additional protection

Troubleshooting

PHPStorm "StandaloneCoroutine was cancelled" Error: This error has been fixed in the current version. The server now properly implements JSON-RPC 2.0 protocol with:

• Correct initialization state tracking
• Proper notification handling (notifications/initialized)
• Better error response formatting
• Improved I/O synchronization

Connection Issues:

• Ensure your DDEV project is running: ddev start
• Check that the port matches what ddev describe shows
• Verify the database name exists

Permission Issues:

• Make sure the start script is executable: chmod +x start_server.sh
• Ensure Python and pip are properly installed

Testing

Test Basic Functionality:

python3 test_mcp.py

Test Read-Only Security Protection:

python3 test_readonly.py

This will verify that all destructive SQL operations are properly blocked while allowing safe read-only queries.

Development

The MCP server follows the Model Context Protocol specification and can be extended with additional database operations as needed.