Content
# MCP MySQL / MariaDB
MCP (Model Context Protocol) for managing MySQL and MariaDB databases. Exposes query, analysis, modification, and connection configuration tools via FastMCP.
---
## Requirements
- Python 3.10+
- MySQL/MariaDB server
- opencode (or any MCP client)
### MySQL Connector
**Windows / Linux / macOS**
```bash
pip install mysql-connector-python
```
---
## Installation
**1. Clone the repository**
```bash
git clone <repo-url>
cd MCP_MYSQL
```
**2. Create virtual environment**
```bash
# Windows
python -m venv .venv
.venv\Scripts\activate
# Linux
python3 -m venv .venv
source .venv/bin/activate
```
**3. Install dependencies**
```bash
pip install -r requirements.txt
```
---
## MCP configuration in opencode
Add this to your opencode config file (`opencode.json` or `~/.config/opencode/opencode.json`):
**Linux**
```json
{
"mcp": {
"mysql": {
"type": "local",
"enabled": true,
"command": [
"/full/path/to/MCP_MYSQL/.venv/bin/python",
"/full/path/to/MCP_MYSQL/Server.py"
]
}
}
}
```
**Windows**
```json
{
"mcp": {
"mysql": {
"type": "local",
"enabled": true,
"command": [
"C:\\full\\path\\to\\MCP_MYSQL\\.venv\\Scripts\\python.exe",
"C:\\full\\path\\to\\MCP_MYSQL\\Server.py"
]
}
}
}
```
---
## Getting started (configuring the connection)
When the MCP starts for the first time, the connection is empty. The assistant will guide you to configure it using these tools:
| Tool | Parameters | Description |
|---|---|---|
| `configure_connection` | host, port, database, user, password, sql_repository | Sets all parameters at once |
| `set_config` | host, port, database, user, password, sql_repository | Updates only the given fields (the rest are preserved) |
| `get_config` | — | Shows the current config (password is hidden) |
| `test_connection` | database (optional) | Tests connectivity with the current settings |
**Typical flow:**
```
1. configure_connection(
host="localhost",
port="3306",
user="root",
password="my_password",
database="MyDB"
)
2. test_connection()
3. list_databases()
4. list_tables("MyDB")
5. describe_table("MyDB", "MyTable")
```
> The configuration is persisted in `config.json`. You can change host or database at any time by calling `configure_connection` or `set_config` again.
---
## MCP Tools
### Configuration
| Tool | Parameters | Description |
|---|---|---|
| `get_config` | — | Shows current config (password hidden) |
| `set_config` | host, port, database, user, password, sql_repository | Updates specific fields in `config.json` |
| `configure_connection` | host, port, database, user, password, sql_repository | Sets all connection parameters at once |
| `test_connection` | database (optional) | Tests the connection with the current config |
### Object exploration
| Tool | Parameters | Description |
|---|---|---|
| `ping` | — | Checks MySQL/MariaDB connectivity |
| `list_databases` | — | Lists all databases |
| `list_tables` | database | Lists tables in a database |
| `describe_table` | database, table | Columns, types, nulls, defaults |
| `list_procedures` | database | Lists stored procedures |
| `describe_procedure` | database, procedure | Source code and parameters of the SP |
| `list_functions` | database | Lists functions |
| `describe_function` | database, function | Source code and parameters of the function |
| `search_tables` | database, text | Searches tables by partial name (LIKE) |
| `search_columns` | database, text | Searches columns by name across all tables |
| `search_procedures` | database, text | Searches SP by partial name |
| `search_text` | database, text | Searches text in SP/function definitions |
| `list_foreign_keys` | database | Lists all FK in the database |
| `find_relationships` | database, table | Incoming and outgoing relationships of a table |
### Data manipulation
| Tool | Parameters | Description |
|---|---|---|
| `execute_query` | database, query | SELECT or CTE (read-only with validation) |
| `execute_dml` | database, query, confirmed | INSERT/UPDATE/DELETE (requires confirmed=True) |
| `execute_ddl` | database, sql_text, description | CREATE/ALTER with automatic migration |
---
## Change tracking (Logs and migrations)
Every time you run `execute_ddl` (CREATE/ALTER), the system automatically saves the full history in `sql_repository`. You never lose track of what was modified.
### What is saved?
```
sql_repository/
└── MyDB/
├── Procedures/
│ └── MyProcedure/
│ └── Current.sql ← current definition with history
├── Functions/
├── Views/
├── Tables/
├── Migrations/
│ └── Procedures/
│ └── 20260724_001_MyProcedure.sql ← each change is a file
└── Logs/
└── Changes.jsonl ← full audit log in JSONL
```
- **Current.sql**: Contains the current object definition plus a `HISTORY` block with all previous versions, date, author, and summary of each change.
- **Migrations/**: Each DDL generates a versioned SQL file (`YYYYMMDD_NNN_Name.sql`) with the exact change. You can review or revert manually.
- **Logs/Changes.jsonl**: Audit log in JSONL format (one line per change), easy to process with scripts or search with grep.
### Why is this important?
- You can revert to a previous version of any object at any time.
- You know exactly what changed, when, and who did it.
- The full `sql_repository` can be versioned in Git for end-to-end traceability.
