Provides safe MySQL database operations including SELECT queries, table listing, schema inspection, and configurable INSERT/UPDATE/DELETE operations with built-in safety features and SQL injection prevention through prepared statements.
MCP MySQL Server
A Model Context Protocol (MCP) server for MySQL database operations with built-in safety features and operation resistance. Perfect for use with Claude Code, Codex CLI, and other MCP-compatible AI assistants.
Features
Safe MySQL Operations: Execute SELECT queries freely while controlling destructive operations
Operation Resistance: Configurable INSERT, UPDATE, and DELETE restrictions
Schema Protection: DROP, TRUNCATE, and ALTER operations are always blocked
SQL Injection Prevention: Uses prepared statements with parameter binding
Multiple Tools: Query execution, table listing, schema inspection, and database info
Connection Pooling: Efficient connection management for better performance
Detailed Error Reporting: Clear error messages with SQL codes
Quick Start
Option 1: Automated Setup (Easiest)
The script will:
Auto-detect Bun or npm
Install dependencies
Create and optionally configure .env
Build the project
Test database connection
Option 2: Manual Setup
Using Bun (Faster):
Using npm:
Integration Guides
Claude Code Setup - Complete guide for Claude Code integration
Codex CLI Setup - Command-line usage and automation
Usage Examples - Comprehensive query examples and patterns
Configuration
Environment Variables
Create a .env
file (use .env.example
as a template):
MCP Client Configuration
For Claude Code, add to your ~/.config/claude-code/.mcp.json
:
Need more examples? See docs/mcp-config-examples.md for:
Multiple databases
Remote/Docker configurations
Development vs production setups
Platform-specific paths
See the integration guides for detailed setup instructions.
Safety Features
Always Blocked Operations
These operations are always blocked regardless of configuration:
DROP
- Dropping tables/databasesTRUNCATE
- Truncating tablesALTER
- Altering table structure
Configurable Operations
Control these operations via environment variables:
INSERT
- Controlled byALLOW_INSERT_OPERATION
UPDATE
- Controlled byALLOW_UPDATE_OPERATION
DELETE
- Controlled byALLOW_DELETE_OPERATION
Always Allowed Operations
SELECT
- Reading data is always permitted
Available Tools
1. mysql_query
Execute SQL queries with safety restrictions.
Parameters:
query
(string, required): The SQL query to executeparams
(array, optional): Parameters for prepared statement
Example:
Response:
2. mysql_list_tables
List all tables in the current database.
Example Response:
3. mysql_describe_table
Get the structure/schema of a specific table.
Parameters:
table
(string, required): Table name
Example Response:
4. mysql_get_database_info
Get information about the database connection and permissions.
Example Response:
Usage Examples
For comprehensive examples, see examples/usage-examples.md.
Quick Examples
Safe SELECT Query:
Parameterized Query (Prevents SQL Injection):
Data Analysis:
Schema Exploration:
Blocked Operations
When operations are disabled, you'll receive clear error messages:
Enabling Write Operations
To enable write operations, update your .env
:
After changing permissions, restart the MCP server.
Security Best Practices
Default to Read-Only: Keep write operations disabled unless specifically needed
Use Prepared Statements: Always use the
params
array for user inputValidate Table Names: The server validates table names in describe operations
Schema Protection: DROP/TRUNCATE/ALTER are permanently blocked
Connection Pooling: Uses connection pooling for better performance and resource management
Error Handling
The server provides detailed error responses:
Testing and Verification
Quick Tests
Once connected to your MCP client, try these commands:
Check Connection:
Show me the MySQL database informationList Tables:
What tables are in my database?Test Safety Features:
Try to insert a test record into any table(Should be blocked with a clear error message)
Query Data:
Show me sample data from the users table
Verification Checklist
Server shows as connected in MCP client
Database connection info displays correctly
Table listing works
SELECT queries execute successfully
INSERT/UPDATE/DELETE are blocked (default)
Clear error messages for blocked operations
For detailed testing examples, see examples/usage-examples.md.
Development
Project Structure
Contributing
See CONTRIBUTING.md for development guidelines.
Troubleshooting
Connection Issues
Verify MySQL is running:
mysql -u username -p
Check host/port configuration
Verify user credentials
Ensure database exists
Permission Errors
Check MySQL user has required permissions
Verify
ALLOW_*_OPERATION
settings match your needs
Tool Not Found
Ensure the server is properly configured in
.mcp.json
Verify the build succeeded:
ls -la dist/index.js
Check MCP client can find the server
Resources
Quick Start Guide - Get started in 5 minutes
Setup Checklist - Step-by-step setup guide
Documentation Index - All documentation organized
Integration Guides - Claude Code & Codex CLI
Project Improvements - What's new
Support
Issues: Report bugs or request features via GitHub issues
Questions: Check the examples directory for common use cases
Security: For security concerns, please email the maintainers
Changelog
Version 1.0.0
Initial release
Basic MySQL operations (SELECT, INSERT, UPDATE, DELETE)
Safety features and operation resistance
Prepared statements for SQL injection prevention
Connection pooling
Comprehensive documentation
License
MIT - see LICENSE file for details
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Enables secure MySQL database operations through natural language with built-in safety features. Supports SELECT queries by default while providing configurable restrictions for INSERT, UPDATE, and DELETE operations.