sderhy/php-mysql-mcp-server

PHP MySQL MCP Server for Claude Code

A portable, secure, and easy-to-use MySQL database interface for Claude Code using the Model Context Protocol (MCP). Built entirely in PHP with zero dependencies.

🚀 Quick Start

./install-mysql-mcp.sh

Restart Claude Code, and you're done!

📋 What This Does

Gives Claude Code the ability to:

• 📊 List and explore your database tables
• 🔍 Search for data across your database
• 📈 Execute read-only SQL queries
• 📝 Analyze table structures and schemas
• 🔢 Count rows and get statistics

All in natural language! Just ask Claude about your database.

🎯 Features

• 6 Powerful Tools: Everything you need to explore and query databases
• Read-Only & Safe: Only SELECT queries allowed, no data modification
• Zero Dependencies: Pure PHP, no external packages required
• Portable: One script installs everything
• Multi-Database: Connect to multiple databases simultaneously
• SQL Injection Protected: Built-in security measures
• Team-Friendly: Easy to share and deploy

📦 Installation

Prerequisites

• PHP 7.4+ with PDO MySQL extension
• MySQL database access
• Claude Code installed

Install PHP

# macOS
brew install php

# Ubuntu/Debian
sudo apt-get install php-cli php-mysql

# Fedora/CentOS
sudo dnf install php-cli php-mysqlnd

# Verify
php --version
php -m | grep pdo_mysql

Automated Installation (Recommended)

# Clone the repository
git clone git@github.com:sderhy/php-mysql-mcp-server.git
cd php-mysql-mcp-server

# Run the installer
./install-mysql-mcp.sh

The installer will:

1. ✅ Check prerequisites
2. ✅ Ask for database credentials
3. ✅ Test database connection
4. ✅ Create configuration file
5. ✅ Register with Claude Code
6. ✅ Verify installation

Then restart Claude Code and you're ready!

Manual Installation

# 1. Create config
cp mysql-config.example.json mysql-config.json
nano mysql-config.json

# 2. Register with Claude Code
claude mcp add --scope user --transport stdio mysql-mydb -- \
  php $(pwd)/mysql-mcp-server.php

# 3. Verify
claude mcp list

🎮 Usage Examples

Once installed, interact naturally with Claude Code:

You: What tables are in my database?
Claude: [Lists all tables with descriptions]

You: Show me the users table structure
Claude: [Displays columns, types, indexes, and row count]

You: How many active users do I have?
Claude: [Counts rows where status = 'active']

You: Find all orders from last month
Claude: [Executes appropriate SELECT query]

You: Search for email john@example.com
Claude: [Searches across all columns in users table]

🔧 Available Tools

1. list_tables - List all tables (with optional pattern filter)
2. describe_table - Get complete schema information
3. query_database - Execute SELECT queries (max 1000 rows)
4. get_table_row_count - Count rows with optional WHERE clause
5. search_tables - Search for value across all columns
6. get_table_sample - Get sample rows to understand data

🔒 Security

• Read-Only: Only SELECT statements allowed
• SQL Injection Prevention: Input validation and prepared statements
• Credential Protection: Config files are git-ignored
• Rate Limiting: Automatic LIMIT enforcement
• Query Validation: Blocks dangerous SQL keywords

Blocked operations: INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, GRANT, REVOKE

🌍 Distribution & Sharing

Create Portable Package

./create-portable-package.sh

Creates a 12KB tarball with everything needed:

• MCP server implementation
• Installer script
• Configuration template
• Complete documentation

Share with Team

Method 1: Via Git

# Team members clone
git clone git@github.com:sderhy/php-mysql-mcp-server.git
cd php-mysql-mcp-server

# Each person runs
./install-mysql-mcp.sh

Method 2: Via Package

# Create package
./create-portable-package.sh

# Share the tarball
# Each person extracts and runs ./install-mysql-mcp.sh

Note: Credentials are never committed (git-ignored). Each user enters their own.

⚙️ Configuration

Basic Configuration

mysql-config.json:

{
  "host": "localhost",
  "port": 3306,
  "database": "my_database",
  "username": "my_user",
  "password": "my_password",
  "charset": "utf8mb4"
}

Multiple Databases

Install multiple instances:

./install-mysql-mcp.sh  # Name: mysql-production
./install-mysql-mcp.sh  # Name: mysql-staging
./install-mysql-mcp.sh  # Name: mysql-development

Remote Database

Just configure the host:

{
  "host": "db.example.com",
  "port": 3306,
  "database": "production",
  ...
}

SSH Tunnel

# Create tunnel
ssh -L 3307:localhost:3306 user@remote-server

# Configure
{
  "host": "localhost",
  "port": 3307,
  ...
}

🐛 Troubleshooting

Common Issues

Verification Commands

# Check PHP
php --version
php -m | grep pdo_mysql

# Check registration
claude mcp list

# Check Claude Code
# In Claude Code, run: /mcp

# Check logs
tail -f ~/.claude/debug/latest | grep -i mysql

Reset Installation

# Remove server
claude mcp remove mysql-mydb

# Clean config
rm mysql-config.json

# Reinstall
./install-mysql-mcp.sh

📚 Documentation

• - 2-minute quick start
• - Installation & usage guide
• - Complete technical documentation
• - Architecture & file structure
• Claude Code MCP Docs
• Model Context Protocol

🤝 Contributing

This is a reference implementation designed to be:

• Simple: Easy to understand and modify
• Portable: Works anywhere PHP runs
• Secure: Read-only with built-in protections
• Educational: Learn how MCP works

Feel free to:

• Fork and customize for your needs
• Add new tools for specific use cases
• Adapt for other databases (PostgreSQL, SQLite, etc.)
• Share improvements with the community

🌟 Why PHP?

PHP is an excellent choice for MCP servers:

• Ubiquitous: Available on most systems
• Zero Setup: No npm, no virtual environments, no build steps
• Fast: Instant startup, perfect for stdio communication
• Portable: Single file deployments
• Battle-tested: Mature PDO library for database access

📜 License

ISC - Free to use, modify, and distribute

🙏 Acknowledgments

Built for the Claude Code community. Inspired by the need for easy, secure database access in AI-assisted development.

Need Help?

1. Check for quick start
2. Read for installation
3. Review for detailed docs
4. Check troubleshooting section above

Happy Querying! 🎉