MySQL MCP Server

1![Tests](https://github.com/designcomputer/mysql_mcp_server/actions/workflows/test.yml/badge.svg)
2![PyPI - Downloads](https://img.shields.io/pypi/dm/mysql-mcp-server)
3[![smithery badge](https://smithery.ai/badge/mysql-mcp-server)](https://smithery.ai/server/mysql-mcp-server)
4[![MseeP.ai Security Assessment Badge](https://mseep.net/mseep-audited.png)](https://mseep.ai/app/designcomputer-mysql-mcp-server)
5# MySQL MCP Server
6A Model Context Protocol (MCP) implementation that enables secure interaction with MySQL databases. This server component facilitates communication between AI applications (hosts/clients) and MySQL databases, making database exploration and analysis safer and more structured through a controlled interface.
7 
8> **Note**: MySQL MCP Server is not designed to be used as a standalone server, but rather as a communication protocol implementation between AI applications and MySQL databases.
9 
10## Features
11- List available MySQL tables as resources
12- Read table contents
13- Execute SQL queries with proper error handling
14- Secure database access through environment variables
15- Comprehensive logging
16 
17## Installation
18### Manual Installation
19```bash
20pip install mysql-mcp-server
21```
22 
23### Installing via Smithery
24To install MySQL MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mysql-mcp-server):
25```bash
26npx -y @smithery/cli install mysql-mcp-server --client claude
27```
28 
29## Configuration
30Set the following environment variables:
31```bash
32MYSQL_HOST=localhost     # Database host
33MYSQL_PORT=3306         # Optional: Database port (defaults to 3306 if not specified)
34MYSQL_USER=your_username
35MYSQL_PASSWORD=your_password
36MYSQL_DATABASE=your_database
37```
38 
39## Usage
40### With Claude Desktop
41Add this to your `claude_desktop_config.json`:
42```json
43{
44  "mcpServers": {
45    "mysql": {
46      "command": "uv",
47      "args": [
48        "--directory",
49        "path/to/mysql_mcp_server",
50        "run",
51        "mysql_mcp_server"
52      ],
53      "env": {
54        "MYSQL_HOST": "localhost",
55        "MYSQL_PORT": "3306",
56        "MYSQL_USER": "your_username",
57        "MYSQL_PASSWORD": "your_password",
58        "MYSQL_DATABASE": "your_database"
59      }
60    }
61  }
62}
63```
64 
65### With Visual Studio Code
66Add this to your `mcp.json`:
67```json
68{
69  "servers": {
70      "mysql": {
71            "type": "stdio",
72            "command": "uvx",
73            "args": [
74                "--from",
75                "mysql-mcp-server",
76                "mysql_mcp_server"
77            ],
78      "env": {
79        "MYSQL_HOST": "localhost",
80        "MYSQL_PORT": "3306",
81        "MYSQL_USER": "your_username",
82        "MYSQL_PASSWORD": "your_password",
83        "MYSQL_DATABASE": "your_database"
84      }
85    }
86  }
87}
88```
89Note: Will need to install uv for this to work
90 
91### Debugging with MCP Inspector
92While MySQL MCP Server isn't intended to be run standalone or directly from the command line with Python, you can use the MCP Inspector to debug it.
93 
94The MCP Inspector provides a convenient way to test and debug your MCP implementation:
95 
96```bash
97# Install dependencies
98pip install -r requirements.txt
99# Use the MCP Inspector for debugging (do not run directly with Python)
100```
101 
102The MySQL MCP Server is designed to be integrated with AI applications like Claude Desktop and should not be run directly as a standalone Python program.
103 
104## Development
105```bash
106# Clone the repository
107git clone https://github.com/designcomputer/mysql_mcp_server.git
108cd mysql_mcp_server
109# Create virtual environment
110python -m venv venv
111source venv/bin/activate  # or `venv\Scripts\activate` on Windows
112# Install development dependencies
113pip install -r requirements-dev.txt
114# Run tests
115pytest
116```
117 
118## Security Considerations
119- Never commit environment variables or credentials
120- Use a database user with minimal required permissions
121- Consider implementing query whitelisting for production use
122- Monitor and log all database operations
123 
124## Security Best Practices
125This MCP implementation requires database access to function. For security:
1261. **Create a dedicated MySQL user** with minimal permissions
1272. **Never use root credentials** or administrative accounts
1283. **Restrict database access** to only necessary operations
1294. **Enable logging** for audit purposes
1305. **Regular security reviews** of database access
131 
132See [MySQL Security Configuration Guide](https://github.com/designcomputer/mysql_mcp_server/blob/main/SECURITY.md) for detailed instructions on:
133- Creating a restricted MySQL user
134- Setting appropriate permissions
135- Monitoring database access
136- Security best practices
137 
138⚠️ IMPORTANT: Always follow the principle of least privilege when configuring database access.
139 
140## License
141MIT License - see LICENSE file for details.
142 
143## Contributing
1441. Fork the repository
1452. Create your feature branch (`git checkout -b feature/amazing-feature`)
1463. Commit your changes (`git commit -m 'Add some amazing feature'`)
1474. Push to the branch (`git push origin feature/amazing-feature`)
1485. Open a Pull Request
149