capital.hove/read-only-local-mysql-mcp-server
MCP server for read-only MySQL database queries in Claude Desktop
Open source Open in the app JSON README (API)
About
MCP server for read-only MySQL database queries in Claude Desktop
Details
- Kind
- MCP servers
- Topic
- Databases
- Publisher
- capital.hove
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.1
- Stars
- 7
- Forks
- 2
- Last push
- 2026-09-07T08:07:31Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:00:49
- Updated
- 2026-08-29 03:00:49
- Origin id
capital.hove/read-only-local-mysql-mcp-server
README
# MySQL MCP Server
[](https://registry.modelcontextprotocol.io)
[](https://www.npmjs.com/package/@hovecapital/read-only-mysql-mcp-server)
A Model Context Protocol (MCP) server that enables Claude Desktop to interact with MySQL databases through natural language queries.
## Features
- Execute read-only SQL queries through Claude Desktop
- **Dynamic connection configuration** — connect to any MySQL database at runtime via connection string
- Built-in security with query validation (SELECT, WITH, SHOW, DESCRIBE and EXPLAIN only, one statement, no comments) plus a server-side read-only transaction
- Easy integration with Claude Desktop
- JSON formatted query results
- Environment-based configuration for database credentials
## Quick Start
### For Claude Code Users (Recommended - Easiest Method)
```bash
claude mcp add mysql -s user -- npx -y @hovecapital/read-only-mysql-mcp-server@latest
```
Then set your database environment variables:
```bash
export DB_HOST=localhost
export DB_PORT=3306
export DB_DATABASE=your_database_name
export DB_USERNAME=your_username
export DB_PASSWORD=your_password
```
**Done!** Restart Claude Code and ask: "What tables are in my database?"
### For Claude Desktop Users (Manual Configuration)
**1. Open your config file:**
```bash
# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json
# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json
```
**2. Add this configuration:**
```json
{
"mcpServers": {
"mysql": {
"command": "npx",
"args": ["-y", "@hovecapital/read-only-mysql-mcp-server@latest"],
"env": {
"DB_HOST": "localhost",
"DB_PORT": "3306",
"DB_DATABASE": "your_database_name",
"DB_USERNAME": "your_username",
"DB_PASSWORD": "your_password"
}
}
}
}
```
**3. Save, restart Claude Desktop, and test!**
## Prerequisites
- Node.js (v16 or higher) - If using mise, update the command path accordingly
- MySQL database server
- Claude Desktop application
## Installation
### Option 1: Install from MCP Registry (Recommended)
This server is published in the [Model Context Protocol Registry](https://registry.modelcontextprotocol.io) as `capital.hove/read-only-local-mysql-mcp-server`.
#### Method A: Claude Code CLI (Easiest!)
```bash
claude mcp add mysql -s user -- npx -y @hovecapital/read-only-mysql-mcp-server@latest
```
Then configure your database credentials using environment variables. Restart Claude Code and you're done!
**Benefits:**
- One command installation
- No manual JSON editing
- Automatic configuration
#### Method B: Manual JSON Configuration
**For Claude Desktop:**
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"mysql": {
"command": "npx",
"args": ["-y", "@hovecapital/read-only-mysql-mcp-server@latest"],
"env": {
"DB_HOST": "localhost",
"DB_PORT": "3306",
"DB_DATABASE": "your_database_name",
"DB_USERNAME": "your_username",
"DB_PASSWORD": "your_password"
}
}
}
}
```
**For Claude Code:**
Edit `~/.config/claude-code/settings.json` (macOS/Linux) or `%APPDATA%\claude-code\settings.json` (Windows):
```json
{
"mcp": {
"servers": {
"mysql": {
"command": "npx",
"args": ["-y", "@hovecapital/read-only-mysql-mcp-server@latest"],
"env": {
"DB_HOST": "localhost",
"DB_PORT": "3306",
"DB_DATABASE": "your_database_name",
"DB_USERNAME": "your_username",
"DB_PASSWORD": "your_password"
}
}
}
}
}
```
### Option 2: Install from npm
```bash
npm install -g @hovecapital/read-only-mysql-mcp-server
```
### Option 3: Installation with Claude Code
If you're using Claude Code, you can easily install this MCP server:
```bash
# Clone the repository
git clone https://github.com/hovecapital/read-only-local-mysql-mcp-server.git
cd read-only-local-mysql-mcp-server
# Install dependencies and build
npm install
npm run build
```
Then configure Claude Code by adding to your MCP settings.
### Option 4: Manual Installation
#### 1. Clone or Download
Save the repository to a directory on your system:
```bash
mkdir ~/mcp-servers/mysql
cd ~/mcp-servers/mysql
git clone https://github.com/hovecapital/read-only-local-mysql-mcp-server.git .
```
#### 2. Install Dependencies
```bash
npm install
npm run build
```
## Configuration
> **Note:** If you installed via Option 1 (MCP Registry with npx), you've already configured everything! This section is for users who chose Options 2, 3, or 4 (npm or manual installation).
### Claude Code Configuration
If you're using Claude Code with a manual installation, add the MySQL server to your MCP settings:
1. Open your Claude Code settings (typically in `~/.config/claude-code/settings.json` on macOS/Linux or `%APPDATA%\claude-code\settings.json` on Windows)
2. Add the MySQL MCP server configuration:
```json
{
"mcp": {
"servers": {
"mysql": {
"command": "node",
"args": ["/absolute/path/to/read-only-local-mysql-mcp-server/dist/index.js"],
"env": {
"DB_HOST": "localhost",
"DB_PORT": "3306",
"DB_DATABASE": "your_database_name",
"DB_USERNAME": "your_username",
"DB_PASSWORD": "your_password"
}
}
}
}
}
```
1. Restart Claude Code for the changes to take effect.
### Claude Desktop Configuration
If you're using Claude Desktop with a manual installation, open your Claude Desktop configuration file:
**macOS:**
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```
**Windows:**
```bash
%APPDATA%\Claude\claude_desktop_config.json
```
Add the MySQL server configuration:
```json
{
"mcpServers": {
"mysql": {
"command": "node",
"args": ["/absolute/path/to/read-only-local-mysql-mcp-server/dist/index.js"],
"env": {
"DB_HOST": "localhost",
"DB_PORT": "3306",
"DB_DATABASE": "your_database_name",
"DB_USERNAME": "your_username",
"DB_PASSWORD": "your_password"
}
}
}
}
```
### Using mise for Node.js
If you're using [mise](https://mise.jdx.dev/) for Node.js version management, make sure to use the full path to the Node.js executable in your configuration.
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `DB_HOST` | MySQL server hostname | `mysql` |
| `DB_PORT` | MySQL server port | `3306` |
| `DB_DATABASE` | Database name | `database` |
| `DB_USERNAME` | MySQL username | `root` |
| `DB_PASSWORD` | MySQL password | (empty) |
| `DB_ALLOWED_HOSTS` | Comma-separated extra hosts a connection string may point at. `DB_HOST` and loopback are always allowed. | (empty) |
## Usage
1. **Restart Claude Desktop** after updating the configuration
2. **Start chatting** with Claude about your database
### Example Queries
```bash
"Show me all tables in my database"
"What's the structure of the users table?"
"Get the first 10 records from the products table"
"How many orders were placed last month?"
"Show me users with email addresses ending in @gmail.com"
```
Claude will automatically convert your natural language requests into appropriate SQL queries and execute them against your database.
## Tools
### `connect`
Connect to a MySQL database using a connection string. The connection persists for subsequent queries until changed or disconnected.
**Parameters:**
| Parameter | Required | Description |
|-----------|----------|-------------|
| `connectionString` | Yes | MySQL connection string (e.g., `mysql://user:password@host:port/database`) |
### `disconnect`
Disconnect from the current runtime database and revert to the default environment-configured connection. Takes no parameters.
### `query`
Run a read-only SQL query against the currently connected database.
**Parameters:**
| Parameter | Required | Description |
|-----------|----------|-------------|
| `sql` | Yes | SQL query to execute (read-only) |
| `connectionString` | No | MySQL connection string to override the current connection for this query only |
## Dynamic Connection
The server supports switching databases at runtime without restarting. Connection priority:
1. **Per-query `connectionString`** — overrides everything for a single query
2. **Runtime connection** (from `connect` tool) — persists until `disconnect` is called
3. **Environment variables** — the default fallback
**Connection string format:**
```
mysql://username:password@hostname:port/database_name
```
The hostname must be `DB_HOST`, a loopback address, or listed in `DB_ALLOWED_HOSTS`. Any other host is rejected before a connection is attempted, so the tools cannot be used to probe the network. Connection failures return a generic message and the real error is written to stderr.
**Example workflow:**
```
1. connect → mysql://analyst:pass@prod-db:3306/analytics
2. query → SELECT COUNT(*) FROM events
3. query → SELECT * FROM users LIMIT 5 (uses the same analytics connection)
4. query → SELECT * FROM orders LIMIT 5, connectionString: mysql://analyst:pass@prod-db:3306/sales
(one-off override — does not change the stored connection)
5. disconnect → reverts to env var defaults
```
## Security Features
### Read-Only Operations
Queries are checked in two layers:
1. **Query validation** — the statement must start with `SELECT`, `WITH`, `SHOW`, `DESCRIBE` or `EXPLAIN`, contain a single statement, contain no comments, and must not contain state-changing keywords anywhere (for example `UPDATE`, `DELETE`, `INTO OUTFILE`, `INTO DUMPFILE`, `LOAD_FILE`, `FOR UPDATE`, `EXPLAIN ANALYZE`). String literals and backtick identifiers are ignored by this check.
2. **Server-side read-only transaction** — every query runs after `SET SESSION TRANSACTION READ ONLY`, so MySQL itself rejects writes, including writes made inside stored functions.
Use a MySQL user with only `SELECT` privileges as well (see below). The validation blocks the known bypasses, but the database privilege is the final guarantee.
### Recommended Database Setup
For enhanced security, create a dedicated read-only user for the MCP server:
```sql
-- Create a read-only user
CREATE USER 'claude_readonly'@'localhost' IDENTIFIED BY 'secure_password';
-- Grant only SELECT permissions on your specific database
GRANT SELECT ON your_database_name.* TO 'claude_readonly'@'localhost';
-- Apply the changes
FLUSH PRIVILEGES;
```
## Troubleshooting
### Connection Issues
1. **Verify MySQL is running**: Check if your MySQL server is active
2. **Check credentials**: Ensure username/password are correct
3. **Network connectivity**: Confirm Claude Desktop can reach your MySQL server
### Configuration Issues
1. **Restart required**: Always restart Claude Desktop after configuration changes
2. **Path accuracy**: Ensure the absolute path to `dist/index.js` is correct
3. **JSON syntax**: Validate your `claude_desktop_config.json` format
### Debug Mode
To see server logs, you can run the server manually:
```bash
node dist/index.js
```
## File Structure
```bash
~/mcp-servers/mysql/
├── src/
│ └── index.ts
├── dist/
│ ├── index.js
│ └── index.d.ts
├── package.json
├── tsconfig.json
└── node_modules/
```
## Dependencies
- **@modelcontextprotocol/sdk**: MCP protocol implementation
- **mysql2**: Modern MySQL client for Node.js with Promise support
## Contributing
Feel free to submit issues and enhancement requests!
## License
This project is open source and available under the [MIT License](LICENSE).
## Support
If you encounter issues:
1. Check the troubleshooting section above
2. Verify your MySQL connection independently
3. Ensure Claude Desktop is updated to the latest version
4. Review the Claude Desktop MCP documentation
---
**Note**: This server is designed for development and analysis purposes. For production use, consider additional security measures and monitoring.