Database MCP Server
A Model Context Protocol (MCP) server that provides database operations through a standardized interface. This server enables AI assistants and other MCP clients to interact with your MySQL database using natural language commands.
Features
- Database Introspection: List tables, describe schemas, and get table statistics
- CRUD Operations: Create, read, update, and delete operations for Users, Products, and Orders
- Safe SQL Execution: Execute SELECT queries with built-in safety checks
- Health Monitoring: Database connectivity testing
- Pagination Support: Handle large datasets efficiently
- Search Capabilities: Fuzzy search across user data
Quick Start
Prerequisites
- Python 3.8+
- MySQL database server
- MCP-compatible client (Claude Desktop, etc.)
Installation
-
Clone the repository
git clone <repository-url> cd database-mcp -
Install dependencies
pip install -r requirements.txt -
Configure database connection
Create a
.envfile in the project root:DB_USER=your_username DB_PASSWORD=your_password DB_HOST=127.0.0.1 DB_PORT=3306 DB_NAME=your_database_name -
Initialize database tables
The server automatically creates tables on startup using SQLAlchemy models.
Running the Server
python main.py
The server will start and listen for MCP connections.
Database Schema
The server manages the following tables:
Users (user)
id(Primary Key)name(String, 50 chars)email(String, 50 chars, unique)password(String, 100 chars)
Products (product)
id(Primary Key)name(String, 100 chars)price(Float)stock(Integer)
Orders (order_list)
id(Primary Key)user_id(Foreign Key → user.id)product_id(Foreign Key → product.id)quantity(Integer)
Additional Tables
chat_history- Conversation loggingchat_summary- Session summarieschat_user- Chat session usersreminders- User remindersrecommendations- System recommendations
Available Tools
Database Introspection
health_check()- Test database connectivitylist_tables()- Get all table namesdescribe_table(table)- Get table schema detailstable_count(table)- Count rows in a tablesample_rows(table, limit=5)- Get sample data
SQL Execution
run_sql_select(sql, max_rows=1000)- Execute SELECT queries safely
User Management
user_create(name, email, password)- Create new useruser_get(id=None, email=None)- Get user by ID or emailuser_list(limit=100, offset=0, q=None)- List users with searchuser_exists(email)- Check if user existsuser_update(id, updates)- Update user fieldsuser_delete(id)- Delete user
Product Management
product_create(name, price, stock)- Create new productproduct_get(id)- Get product by IDproduct_list(limit=100, offset=0, q=None)- List products with searchproduct_update(id, updates)- Update product fieldsproduct_delete(id)- Delete product
Order Management
order_create(user_id, product_id, quantity)- Create new orderorder_get(id)- Get order by IDorder_list(limit=100, offset=0, user_id=None)- List ordersorder_update(id, updates)- Update orderorder_delete(id)- Delete order
Usage Examples
Basic Database Operations
# Check database health
health_check()
# Returns: {"ok": true}
# List all tables
list_tables()
# Returns: ["user", "product", "order_list", ...]
# Get table schema
describe_table("user")
# Returns detailed column information
User Operations
# Create a user
user_create("John Doe", "john@example.com", "password123")
# Find user by email
user_get(email="john@example.com")
# Search users
user_list(q="john", limit=10)
# Update user
user_update(1, {"name": "John Smith"})
Product Operations
# Create product
product_create("Laptop", 999.99, 50)
# List products with search
product_list(q="laptop", limit=20)
# Update stock
product_update(1, {"stock": 45})
Order Operations
# Create order
order_create(user_id=1, product_id=1, quantity=2)
# Get user's orders
order_list(user_id=1)
MCP Client Configuration
Claude Desktop
Add to your Claude Desktop configuration:
{
"mcpServers": {
"database": {
"command": "python",
"args": ["path/to/database-mcp/main.py"],
"env": {
"DB_USER": "your_username",
"DB_PASSWORD": "your_password",
"DB_HOST": "127.0.0.1",
"DB_PORT": "3306",
"DB_NAME": "your_database"
}
}
}
}
Security Features
- SQL Injection Protection: Uses parameterized queries
- Read-Only SQL:
run_sql_selectonly allows SELECT statements - Row Limits: Automatic pagination and row count limits
- Input Validation: Type checking and bounds validation
Error Handling
The server includes comprehensive error handling:
- Database connection failures
- Invalid SQL queries
- Missing records
- Constraint violations
All errors are logged and return user-friendly messages.
Development
Project Structure
database-mcp/
├── main.py # MCP server implementation
├── database.py # Database connection setup
├── models.py # SQLAlchemy models
├── requirements.txt # Python dependencies
├── .env # Environment configuration
└── schemas/ # Pydantic schemas (optional)
├── user_schema.py
├── product_schema.py
└── order_schema.py
Adding New Models
- Define model in
models.py - Add CRUD tools in
main.py - Update database schema as needed
Testing
Test database connectivity:
python -c "from main import health_check; print(health_check())"
Troubleshooting
Common Issues
Connection Refused
- Check MySQL server is running
- Verify connection credentials in
.env - Ensure database exists
Import Errors
- Install all requirements:
pip install -r requirements.txt - Check Python version compatibility
Permission Denied
- Verify database user has necessary privileges
- Check firewall settings
Logging
The server logs errors to help with debugging. Check console output for detailed error messages.
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
For issues and questions:
- Check the troubleshooting section
- Review server logs for error details
- Open an issue on GitHub
Note: This MCP server is designed for development and testing. For production use, implement additional security measures, authentication, and monitoring.