Amazon Q CLI with MySQL MCP Server Integration

A comprehensive guide for integrating AWS RDS MySQL MCP server with Amazon Q CLI, enabling natural language database interactions through Amazon Q's conversational interface.

Overview

This project demonstrates how to configure Amazon Q CLI to work with a FastMCP MySQL server, allowing you to interact with your AWS RDS MySQL database using natural language commands through Amazon Q's chat interface.

Prerequisites

• Python 3.8 or higher
• Amazon Q CLI installed and configured
• AWS RDS MySQL instance or local MySQL server
• AWS CLI configured with appropriate permissions

Installation & Setup

1. Install Amazon Q CLI

Follow the installation guide:

• Reference: Installing Amazon Q Developer CLI

2. Create Virtual Environment

# Create isolated virtual environment
python3 -m venv venv-mcp

# Activate virtual environment
# Linux/macOS:
source venv-mcp/bin/activate

3. Install Dependencies

pip3 install fastmcp pymysql boto3 python-dotenv

4. Environment Configuration

# Copy the example environment file
cp .env.example .env

# Edit .env with your actual configuration

Configure your .env file:

# AWS Configuration
AWS_REGION=us-east-1
BEDROCK_MODEL_ID=anthropic.claude-3-haiku-20240307-v1:0

# MySQL Database Configuration
RDS_HOST=your-mysql-host.amazonaws.com
RDS_PORT=3306
RDS_USER=your-username
RDS_PASS=your-password
RDS_DB=your-database-name

Security Best Practices:

• Never commit .env files to version control
• Add .env to your .gitignore file
• Use AWS IAM roles in production environments
• Regularly rotate database credentials

MCP Configuration Options

Amazon Q CLI supports two MCP configuration modes: (We will be implementing Global Configuration)

Workspace Configuration

• Scope: Directory-specific
• Location: /.amazonq/mcp.json in working directory
• Usage: Must run Q CLI commands from the configured directory

Global Configuration (Recommended)

• Scope: System-wide access
• Location: ~/.aws/amazonq/mcp.json
• Usage: Run Q CLI commands from any directory
• Benefit: Persistent across system reboots

Global MCP Setup (Recommended)

1. Create Configuration Directory

# Create Amazon Q configuration directory
mkdir -p ~/.aws/amazonq

2. Create MCP Configuration File

Create ~/.aws/amazonq/mcp.json with the following content:

{
  "mcpServers": {
    "rds_mysql_server": {
      "command": "/absolute/path/to/your/venv-mcp/bin/python3",
      "args": [
        "/absolute/path/to/your/fastmcp_server.py"
      ],
      "env": {},
      "timeout": 120000,
      "disabled": false
    }
  }
}

Important: Replace paths with your actual absolute paths:

• /absolute/path/to/your/venv-mcp/bin/python3
• /absolute/path/to/your/fastmcp_server.py

3. Verify Configuration

q mcp list

Expected Output:

workspace:
  /.amazonq/mcp.json
    (empty)

global:
  /home/username/.aws/amazonq/mcp.json
    • rds_mysql_server /path/to/venv-mcp/bin/python3

Usage

Start Amazon Q Chat

q chat

Example Database Interactions

# Natural language queries
"Show me all tables in the database"
"Create a users table with id, name, and email columns"
"Find all records in the users table"
"Insert a new user with name 'John Doe' and email 'john@example.com' in users table"
"Show the structure of the users table"

Security Features

• Input Validation: Prevents malicious SQL injection
• Operation Restrictions: Blocks dangerous operations (DROP DATABASE, TRUNCATE)
• Connection Timeout: 120-second timeout prevents hanging connections
• Environment Isolation: Secure credential management through .env files
• Error Handling: Graceful error responses without exposing sensitive information

Supported Operations

Troubleshooting

Common Issues

1. MCP Server Not Found

   • Verify absolute paths in mcp.json
   • Ensure virtual environment is properly created
   • Check file permissions

2. Database Connection Failed

   • Validate .env configuration
   • Test database connectivity
   • Check firewall settings

3. Permission Denied

   • Verify AWS credentials
   • Check database user permissions
   • Ensure proper IAM roles

Debug Commands

# Test MCP server directly
python3 fastmcp_server.py

# Verify environment variables
echo $AWS_REGION

# Check Q CLI configuration
q mcp list
q chat --debug

Configuration Management

Update MCP Server

1. Stop any running Q chat sessions
2. Update fastmcp_server.py or configuration
3. Restart Q chat: q chat

Disable MCP Server

{
  "mcpServers": {
    "rds_mysql_server": {
      "disabled": true
    }
  }
}

Performance Optimization

• Connection Pooling: Reuse database connections
• Query Caching: Cache frequently accessed data
• Timeout Management: Optimize timeout values based on query complexity
• Resource Monitoring: Monitor CPU and memory usage

Next Steps

1. Extend Functionality: Add custom tools for specific business logic
2. Multi-Database Support: Configure multiple database connections
3. Advanced Security: Implement role-based access control
4. Monitoring: Set up logging and performance monitoring
5. Automation: Create deployment scripts for team environments

Note: This configuration provides persistent, system-wide access to your MySQL database through Amazon Q CLI's natural language interface. Always follow security best practices when handling database credentials and connections.