# MCP mysql

<p align="center">
  <img src="./assets/logo.png" alt="MCP mysql logo" width="96" height="96" />
</p>

<p align="center">
  <strong>Local Cursor plugin / MCP server for MySQL &amp; MariaDB</strong><br/>
  Inspect schema · query data · mutate safely · read-only by default
</p>

<p align="center">
  <a href="https://github.com/ismaelrodimb/mcp-mysql-server"><img alt="GitHub" src="https://img.shields.io/badge/GitHub-ismaelrodimb%2Fmcp--mysql--server-181717?logo=github" /></a>
  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
  <img alt="Node.js 20+" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white" />
  <img alt="MCP" src="https://img.shields.io/badge/Protocol-MCP-6E56CF" />
  <img alt="Default mode" src="https://img.shields.io/badge/Default-read--only-2ea44f" />
</p>

<p align="center">
  <a href="./README.es.md">Español</a>
  ·
  <a href="./docs/README.md">Docs</a>
  ·
  <a href="./docs/INSTALL.md">Installation</a>
  ·
  <a href="./docs/SUPPORT.md">Support</a>
  ·
  <a href="https://github.com/ismaelrodimb">Author</a>
</p>

---

## Overview

**MCP mysql** is a [Model Context Protocol](https://modelcontextprotocol.io/) server for [Cursor](https://cursor.com/). It connects **directly to MySQL/MariaDB**.

> **Not a phpMyAdmin integration.** phpMyAdmin does not expose an MCP API. This plugin talks to the database server itself — the same kind of backend phpMyAdmin can use — not to the phpMyAdmin web UI.

The repo ships as a local Cursor plugin (`.cursor-plugin/plugin.json` + `mcp.json`) and includes an agent skill at `skills/mysql-best-practices/SKILL.md`.

| | |
|---|---|
| **Author** | [Ismael Rodríguez](https://github.com/ismaelrodimb) |
| **Repository** | [ismaelrodimb/mcp-mysql-server](https://github.com/ismaelrodimb/mcp-mysql-server) |
| **License** | [MIT](./LICENSE) |
| **Docs** | [docs/README.md](./docs/README.md) |
| **Privacy** | [docs/PRIVACY.md](./docs/PRIVACY.md) |
| **Support** | [docs/SUPPORT.md](./docs/SUPPORT.md) |
| **Security** | [docs/SECURITY.md](./docs/SECURITY.md) |

---

## Features

| Area | Capabilities |
|---|---|
| **Discover** | List databases and tables |
| **Schema** | Describe columns, primary keys, and foreign keys |
| **Resources** | Full schema via MCP resources (per DB / per table) |
| **DDL** | Create/drop tables · add/drop columns |
| **DML** | Select, insert, update, delete rows (write mode dependent) |

---

## Security

Starts in **`read-only`** by default.

| Mode | Behavior |
|---|---|
| `none` | Writes disabled |
| `read-only` | Read access only *(recommended to start)* |
| `full` | Allows `INSERT`, `UPDATE`, `DELETE`, and schema changes |

> Prefer a least-privilege MySQL user. Never commit real passwords to shared configs.

---

## Requirements

- **Node.js** 20+
- **MySQL** or **MariaDB** reachable from this machine
- Database credentials

---

## Quick start

Full guides: **[docs/INSTALL.md](./docs/INSTALL.md)** · **[docs/es/INSTALL.md](./docs/es/INSTALL.md)**

```bash
npm install
npm run build
```

Install as a local Cursor plugin (example path on Windows):

```text
C:\Users\<YOUR_USER>\.cursor\plugins\local\mcp-mysql-server
```

Then enable **MCP mysql** in Cursor and set `MYSQL_*` + `MCP_WRITE_MODE`.

> The plugin `mcp.json` uses `./dist/index.js` (relative) to avoid Windows path bugs such as `C:\c:\Users\...`.

---

## Development

```bash
# watch / run from source
npm run dev

# production build
npm run build
npm start
```

---

## MCP tools

### Read

| Tool | Description |
|---|---|
| `list_databases` | List available databases |
| `list_tables` | List tables in a database |
| `describe_table` | Column metadata for a table |
| `inspect_database_schema` | Full schema for a database |
| `inspect_table_relationships` | Primary and foreign keys |
| `select_rows` | Read rows with simple filters |

### Write / schema

| Tool | Description |
|---|---|
| `insert_row` | Insert a row |
| `update_rows` | Update rows (filters required) |
| `delete_rows` | Delete rows (filters + confirmation) |
| `create_table` | Create a table |
| `drop_table` | Drop a table (confirmation required) |
| `add_column` | Add a column |
| `drop_column` | Drop a column (confirmation required) |

---

## MCP resources

| URI | Returns |
|---|---|
| `mysql://databases` | Available databases |
| `mysql://schema/{database}` | Full schema (tables, columns, keys, relations) |
| `mysql://table/{database}/{table}` | Single-table detail |

---

## Limitations

- No free-form arbitrary SQL execution
- Identifiers limited to alphanumeric characters and `_`
- Filters support: `=`, `!=`, `>`, `>=`, `<`, `<=`, `LIKE`, `IN`

---

## Support, privacy & security

| Topic | Document |
|---|---|
| Docs index | [docs/README.md](./docs/README.md) |
| End-user support | [docs/SUPPORT.md](./docs/SUPPORT.md) |
| Contributing | [docs/CONTRIBUTING.md](./docs/CONTRIBUTING.md) · [docs/es/CONTRIBUTING.md](./docs/es/CONTRIBUTING.md) |
| Code of conduct | [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) |
| Privacy policy | [docs/PRIVACY.md](./docs/PRIVACY.md) · [docs/es/PRIVACY.md](./docs/es/PRIVACY.md) |
| Security reporting | [docs/SECURITY.md](./docs/SECURITY.md) |
| License | [LICENSE](./LICENSE) (MIT) |

Support is provided by the publisher via [GitHub Issues](https://github.com/ismaelrodimb/mcp-mysql-server/issues) (use the bug / feature templates). Cursor / Anysphere do not provide support for this third-party plugin.

---

## Contributing

See [docs/CONTRIBUTING.md](./docs/CONTRIBUTING.md) for the issue process, development setup, and PR guidelines.

---

## Documentation

All guides live under [`docs/`](./docs/README.md) (English) and [`docs/es/`](./docs/README.es.md) (Spanish).

| Document | English | Español |
|---|---|---|
| Docs index | [docs/README.md](./docs/README.md) | [docs/README.es.md](./docs/README.es.md) |
| Installation | [docs/INSTALL.md](./docs/INSTALL.md) | [docs/es/INSTALL.md](./docs/es/INSTALL.md) |
| Contributing | [docs/CONTRIBUTING.md](./docs/CONTRIBUTING.md) | [docs/es/CONTRIBUTING.md](./docs/es/CONTRIBUTING.md) |
| Support | [docs/SUPPORT.md](./docs/SUPPORT.md) | [docs/es/SUPPORT.md](./docs/es/SUPPORT.md) |
| Privacy | [docs/PRIVACY.md](./docs/PRIVACY.md) | [docs/es/PRIVACY.md](./docs/es/PRIVACY.md) |
| Security | [docs/SECURITY.md](./docs/SECURITY.md) | [docs/es/SECURITY.md](./docs/es/SECURITY.md) |
| Code of conduct | [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) | — |

---

<p align="center">
  Made by <a href="https://github.com/ismaelrodimb">Ismael Rodríguez</a>
</p>