Skip to content
Back to search

mysql_mcp_server

A Model Context Protocol (MCP) server that enables secure interaction with MySQL databases

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/designcomputer--mysql-mcp-server/badge.svg)](/listings/designcomputer--mysql-mcp-server)

HTML

<a href="/listings/designcomputer--mysql-mcp-server"><img src="/api/listings/designcomputer--mysql-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Manual Installation

pip install mysql-mcp-server

Installing via Smithery

To install MySQL MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/designcomputer/mysql-mcp-server):

npx -y @smithery/cli install designcomputer/mysql-mcp-server --client claude

Installing via Claude Code CLI

claude mcp add --transport stdio designcomputer-mysql_mcp_server uvx mysql_mcp_server

Installing via Autohand Code CLI

autohand mcp add mysql env MYSQL_HOST=localhost MYSQL_PORT=3306 MYSQL_USER=your_username MYSQL_PASSWORD=your_password MYSQL_DATABASE=your_database uvx mysql_mcp_server

Add `--scope project` after `mcp add` to keep the registration in the current workspace. See [Autohand Code](https://github.com/autohandai/code-cli/) for current CLI details.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 276 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. [![Tests](https://github.com/designcomputer/mysql_mcp_server/actions/workflows/test.yml/badge.svg)](https://github.com/designcomputer/mysql_mcp_server/actions)
  2. [![PyPI - Downloads](https://img.shields.io/pypi/dm/mysql-mcp-server)](https://pypi.org/project/mysql-mcp-server/)
  3. [![AgentAudit Safe](https://img.shields.io/badge/AgentAudit-safe-brightgreen)](https://www.agentaudit.dev/packages/mysql-mcp-server)
  4. # MySQL MCP Server
  5. A 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.
  6. > **Note**: MySQL MCP Server supports both standard input/output (STDIO) and Streamable HTTP (SSE) transport modes. The SSE mode is recommended for remote/self-hosted deployments.
  7. ## Deployment options
  8. - **Hosted** — [Fronteir AI](https://fronteir.ai/mcp/designcomputer-mysql-mcp-server) runs the server for you; no local setup required.
  9. - **Local** — install from PyPI and run the server on your own machine (see [Installation](#installation)).
  10. ## Features
  11. - List available MySQL tables as resources
  12. - Read table contents
  13. - Execute SQL queries with proper error handling
  14. - **Multi-database mode** (Optional `MYSQL_DATABASE`)
  15. - **SSE/HTTP transport support** (`MCP_TRANSPORT=sse`)
  16. - **SSH Tunneling support**
  17. - **Comprehensive schema information**
  18. - **Table data sampling**
  19. - Secure database access through environment variables
  20. - Comprehensive logging
  21. ## Installation
  22. ### Manual Installation
  23. ```bash
  24. pip install mysql-mcp-server
  25. ```
  26. ### Installing via Claude Code CLI
  27. ```bash
  28. claude mcp add --transport stdio designcomputer-mysql_mcp_server uvx mysql_mcp_server
  29. ```
  30. ### Installing via Autohand Code CLI
  31. ```bash
  32. autohand mcp add mysql env MYSQL_HOST=localhost MYSQL_PORT=3306 MYSQL_USER=your_username MYSQL_PASSWORD=your_password MYSQL_DATABASE=your_database uvx mysql_mcp_server
  33. ```
  34. Add `--scope project` after `mcp add` to keep the registration in the current workspace. See [Autohand Code](https://github.com/autohandai/code-cli/) for current CLI details.
  35. ## Configuration
  36. Set the following environment variables:
  37. ```bash
  38. MYSQL_HOST=localhost # Database host
  39. MYSQL_PORT=3306 # Optional: Database port (defaults to 3306 if not specified)
  40. MYSQL_USER=your_username
  41. MYSQL_PASSWORD=your_password
  42. MYSQL_DATABASE=your_database # Optional: Omit for multi-database mode
  43. # Advanced Configuration
  44. MYSQL_SSL_MODE=DISABLED # DISABLED, REQUIRED, VERIFY_CA, VERIFY_IDENTITY
  45. MYSQL_CONNECT_TIMEOUT=10 # Timeout in seconds
  46. # Connection behaviour (Optional)
  47. MYSQL_SQL_MODE=TRADITIONAL # SQL mode applied to the connection (default: TRADITIONAL)
  48. # Compatibility (Optional)
  49. MYSQL_CHARSET=utf8mb4
  50. MYSQL_COLLATION=utf8mb4_unicode_ci
  51. MYSQL_AUTH_PLUGIN= # e.g., mysql_native_password for older MySQL versions
  52. MYSQL_USE_PURE=false # Force the pure-Python connector (default: false)
  53. MYSQL_RAISE_ON_WARNINGS=false # Raise on SQL warnings (default: false)
  54. # SSE Transport (Optional)
  55. MCP_TRANSPORT=stdio # stdio or sse
  56. MCP_SSE_HOST=0.0.0.0 # Listen on all interfaces (required for Docker/hosting)
  57. PORT=8000 # HTTP port (fallback for MCP_SSE_PORT)
  58. MCP_SSE_ALLOWED_HOSTS= # Comma-separated allowed Host headers (default: localhost:{port},127.0.0.1:{port})
  59. # SSH Tunneling (Optional)
  60. MYSQL_SSH_ENABLE=false # Set to true to enable
  61. MYSQL_SSH_HOST= # SSH jump host
  62. MYSQL_SSH_PORT=22 # SSH port
  63. MYSQL_SSH_USER= # SSH username
  64. MYSQL_SSH_KEY_PATH= # Path to SSH private key
  65. MYSQL_SSH_REMOTE_HOST=localhost # Host from the perspective of the jump host
  66. MYSQL_SSH_REMOTE_PORT=3306
  67. MYSQL_LOCAL_PORT=3330
  68. ```
  69. ### `.env` file loading
  70. On startup the server automatically loads a `.env` file via `python-dotenv`, so for local use you can simply:
  71. ```bash
  72. cp .env.example .env # then edit with your credentials
  73. ```
  74. The file is read from the **process working directory** (and parent directories), which works when you run the server yourself from the project folder.
  75. > ⚠️ **Claude Code / Claude Desktop:** these hosts launch the server from their own working directory, so the project's `.env` will **not** be found and you'll see `Missing required database configuration`. Put your `MYSQL_*` values in the `env` block of the MCP config (shown in the Usage section below) rather than relying on `.env`.
  76. ### Multi-Database Mode
  77. When `MYSQL_DATABASE` is not set, the server operates in multi-database mode:
  78. - `list_resources` returns all user databases (system databases are filtered out)
  79. - Use fully qualified table names like `mydb.mytable` in SQL queries
  80. - **Note:** Only single SQL statements are supported. Multi-statement queries (e.g., `USE db; SELECT ...`) are not supported.
  81. ## Available Tools
  82. ### `execute_sql`
  83. Executes any standard SQL query.
  84. - **Arguments:** `query` (string)
  85. - **Features:** Supports `SELECT`, `SHOW`, `DESCRIBE`, and DML (`INSERT`, `UPDATE`, `DELETE`). DML operations are marked with a destructive hint.
  86. - **Limitation:** Single statements only. Multi-statement queries are not supported.
  87. - **Cross-database:** Use `database.table` notation to query any database regardless of the `MYSQL_DATABASE` setting.
  88. ### `get_schema_info`
  89. Provides detailed metadata about database structures.
  90. - **Arguments:** `table_name` (optional string)
  91. - **Output:** Column names, types, nullability, default values, and comments.
  92. - **Cross-database:** Pass `database.table` to query a table outside `MYSQL_DATABASE`; bare names use the configured database.
  93. - **Identifier rules:** Names must contain only alphanumeric characters, underscores, and `$` (dots are allowed as a separator between database and table names).
  94. ### `get_table_sample`
  95. Fetches a representative sample of data.
  96. - **Arguments:** `table_name` (string), `limit` (optional integer, max 20)
  97. - **Use Case:** Quickly understand data formats and content without fetching large result sets.
  98. - **Cross-database:** Pass `database.table` to sample a table outside `MYSQL_DATABASE`; bare names use the configured database.
  99. - **Identifier rules:** Names must contain only alphanumeric characters, underscores, and `$` (dots are allowed as a separator between database and table names).
  100. ## Available Prompts
  101. In addition to tools, the server exposes **MCP prompts** — guided, multi-step workflows that a client can launch on demand. In Claude Code they appear as slash commands (`/mcp__<server>__<prompt>`); in Claude Desktop they appear in the prompts (`+`) menu.
  102. | Prompt | Arguments | Description |
  103. | --- | --- | --- |
  104. | `explore_database` | *(none)* | Systematically explore the database: discover available tables, inspect their schemas, sample the data, and summarize what's there. |
  105. | `analyze_table` | `table_name` *(required)* | Deep-dive into a specific table: retrieve its schema, sample its data, and suggest useful queries. Accepts `database.table` notation for cross-database lookups. |
  106. **Example (Claude Code):**
  107. ```
  108. /mcp__mysql__explore_database
  109. /mcp__mysql__analyze_table customers
  110. ```
  111. Both prompts orchestrate the existing `get_schema_info` and `get_table_sample` tools; `explore_database` also uses resource listing to enumerate tables.
  112. ## Usage
  113. ### With Claude Desktop
  114. Add this to your `claude_desktop_config.json`:
  115. ```json
  116. {
  117. "mcpServers": {
  118. "mysql": {
  119. "command": "uv",
  120. "args": [
  121. "--directory",
  122. "path/to/mysql_mcp_server",
  123. "run",
  124. "mysql_mcp_server"
  125. ],
  126. "env": {
  127. "MYSQL_HOST": "localhost",
  128. "MYSQL_PORT": "3306",
  129. "MYSQL_USER": "your_username",
  130. "MYSQL_PASSWORD": "your_password",
  131. "MYSQL_DATABASE": "your_database"
  132. }
  133. }
  134. }
  135. }
  136. ```
  137. For more detailed examples and agent-specific guidance, see [MCP_USECASES.md](MCP_USECASES.md).
  138. ### With Visual Studio Code
  139. Add this to your `mcp.json`:
  140. ```json
  141. {
  142. "mcpServers": {
  143. "mysql": {
  144. "type": "stdio",
  145. "command": "uvx",
  146. "args": [
  147. "--from",
  148. "mysql-mcp-server",
  149. "mysql_mcp_server"
  150. ],
  151. "env": {
  152. "MYSQL_HOST": "localhost",
  153. "MYSQL_PORT": "3306",
  154. "MYSQL_USER": "your_username",
  155. "MYSQL_PASSWORD": "your_password",
  156. "MYSQL_DATABASE": "your_database"
  157. }
  158. }
  159. }
  160. }
  161. ```
  162. Note: Will need to install uv for this to work
  163. ### Debugging with MCP Inspector
  164. While 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.
  165. The MCP Inspector provides a convenient way to test and debug your MCP implementation:
  166. ```bash
  167. # Install dependencies
  168. pip install -r requirements.txt
  169. # Use the MCP Inspector for debugging (do not run directly with Python)
  170. ```
  171. The 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.
  172. ## Development
  173. ```bash
  174. # Clone the repository
  175. git clone https://github.com/designcomputer/mysql_mcp_server.git
  176. cd mysql_mcp_server
  177. # Create virtual environment
  178. python -m venv venv
  179. source venv/bin/activate # or `venv\Scripts\activate` on Windows
  180. # Install development dependencies
  181. pip install -r requirements-dev.txt
  182. # Copy the example config and edit with your credentials
  183. cp .env.example .env
  184. # Edit .env with your MySQL connection details
  185. # Run tests
  186. pytest
  187. ```
  188. ## Security Considerations
  189. - **Identifier Validation:** Table and database names passed to `get_schema_info` and `get_table_sample` are validated against a strict whitelist (alphanumeric, underscore, and `$` only; a single dot is allowed as a `database.table` separator). Other special characters are rejected to prevent SQL injection.
  190. - **Encrypted Access:** Full support for SSL/TLS and SSH Tunneling for secure remote connections.
  191. - **Log Privacy:** Passwords and SSH private keys are automatically masked in server logs.
  192. - **Least Privilege:** Always use a dedicated MySQL user with minimal required permissions.
  193. - **SSE transport has no built-in authentication.** The SSE server binds to `0.0.0.0` by default and accepts connections without credentials. If you expose it beyond localhost, place it behind a reverse proxy (nginx, Caddy, Traefik) that enforces authentication. Example with nginx and HTTP Basic Auth:
  194. ```nginx
  195. location /sse {
  196. auth_basic "MCP";
  197. auth_basic_user_file /etc/nginx/.htpasswd;
  198. proxy_pass http://127.0.0.1:8000;
  199. proxy_set_header Host $host;
  200. proxy_buffering off;
  201. }
  202. location /messages/ {
  203. auth_basic "MCP";
  204. auth_basic_user_file /etc/nginx/.htpasswd;
  205. proxy_pass http://127.0.0.1:8000;
  206. proxy_set_header Host $host;
  207. }
  208. ```
  209. Set `MCP_SSE_HOST=127.0.0.1` so the server only listens on loopback and the proxy is the sole public entry point. Set `MCP_SSE_ALLOWED_HOSTS` to the public hostname your proxy forwards (e.g. `MCP_SSE_ALLOWED_HOSTS=myserver.example.com:443`).
  210. See [SECURITY.md](SECURITY.md) for a comprehensive guide on securing your deployment.
  211. ## Security Best Practices
  212. This MCP implementation requires database access to function. For security:
  213. 1. **Create a dedicated MySQL user** with minimal permissions
  214. 2. **Never use root credentials** or administrative accounts
  215. 3. **Restrict database access** to only necessary operations
  216. 4. **Enable logging** for audit purposes
  217. 5. **Regular security reviews** of database access
  218. See [MySQL Security Configuration Guide](https://github.com/designcomputer/mysql_mcp_server/blob/main/SECURITY.md) for detailed instructions on:
  219. - Creating a restricted MySQL user
  220. - Setting appropriate permissions
  221. - Monitoring database access
  222. - Security best practices
  223. ⚠️ IMPORTANT: Always follow the principle of least privilege when configuring database access.
  224. ## License
  225. MIT License - see LICENSE file for details.
  226. ## Contributing
  227. 1. Fork the repository
  228. 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
  229. 3. Commit your changes (`git commit -m 'Add some amazing feature'`)
  230. 4. Push to the branch (`git push origin feature/amazing-feature`)
  231. 5. Open a Pull Request

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.