Text-to-SQL (MySQL) MCP server for AI agents

This MCP (Model Context Protocol) server provides secure database query services through a FastMCP framework. It connects to MySQL databases and offers authentication, permission management, and safe SQL query execution capabilities.

Installation

Installing Dependencies

Before using the Text-to-SQL MCP server, you need to install the required dependencies:

pip install -r requirements.txt

The server requires Python 3.10 or higher and depends on the following packages:

fastmcp (v2.10.6) - MCP server framework
python-dotenv (v1.1.0) - Environment variable management
mysql-connector-python (v8.2.0) - MySQL database connector
uvicorn (v0.24.0) - ASGI server

Configuration

1. Environment Variables Setup

Copy the example environment file and configure it with your database connection details:

cp .env.example .env

Edit the .env file with your specific settings:

# Database configuration
DB_HOST=localhost
DB_PORT=3306
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database

# Optional: Server configuration
MCP_HOST=127.0.0.1
MCP_PORT=8000

2. Database Initialization

Initialize your database with the example data:

mysql -u your_username -p your_database < dataset.sql

This will create a sample contracts table with contract information.

Usage

Starting the Server

To start the MCP server, run:

python mcp_server.py

Upon successful startup, you'll see output similar to:

Authorization=Bearer ...
🚀 Starting MCP Data Query Server...
📍 Address: http://127.0.0.1:8000
📋 Available tools:
   - health_check: Health check
   - get_user_permissions: Get user permissions
   - get_database_tables: Get database tables list
   - get_table_structure: Get table structure
   - execute_sql_query: Execute SQL query
   - generate_sql_from_question: Generate SQL from natural language
   - analyze_query_result: Analyze query results

Available API Tools

1. Health Check

Tool name: health_check
Description: Checks the service and database connection status
Permissions: No special permissions required

2. Get User Permissions

Tool name: get_user_permissions
Description: Retrieves current user's permission information
Permissions: Requires a valid access token

3. Get Database Tables List

Tool name: get_database_tables
Description: Retrieves a list of all tables in the database
Permissions: Requires data:read_tables permission

4. Get Table Structure

Tool name: get_table_structure
Parameters:
- table_name (string): Table name
Description: Gets structure information, row count, and sample data for a specific table
Permissions: Requires data:read_tables permission

5. Execute SQL Query

Tool name: execute_sql_query
Parameters:
- sql_query (string): SQL query statement
- limit (int, optional): Maximum number of rows to return, default 100
Description: Safely executes SQL queries
Permissions: Requires data:read_table_data permission
Security Restrictions: Prohibits DROP, DELETE, UPDATE, INSERT and other modification operations

Security Features

Permission System

JWT Token authentication based on RSA key pairs
Fine-grained permission control:
- data:read_tables: Permission to read table structures
- data:read_table_data: Permission to read table data

Security Checks

SQL Injection Protection: Prohibits dangerous SQL operations
Query Limitations: Automatically adds LIMIT constraints to prevent large data queries
Sensitive Data Protection: Additional permission checks for queries containing sensitive keywords

Important Notes

Database Security: Ensure database user permissions are minimized, granting only necessary query privileges
Network Security: For production environments, use HTTPS and firewall protection
Token Management: Regularly update access tokens to avoid using the same token for extended periods
Query Monitoring: Monitor query performance to prevent complex queries from affecting database performance

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "text-to-sql-mysql" '{"command":"python","args":["mcp_server.py"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "text-to-sql-mysql": {
            "command": "python",
            "args": [
                "mcp_server.py"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "text-to-sql-mysql": {
            "command": "python",
            "args": [
                "mcp_server.py"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect