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.