# sqlx-mcp
[](https://crates.io/crates/sqlx-mcp)
[](https://docs.rs/sqlx-mcp)
[](https://github.com/epicsagas/sqlx-mcp/blob/main/LICENSE)
[](https://crates.io/crates/sqlx-mcp)
[](https://buymeacoffee.com/epicsaga)
A Rust-based MCP (Model Context Protocol) server providing secure multi-database operations for MCP clients.
## Features
- **Multi-Engine Support** - MySQL, PostgreSQL, SQLite
- **Multiple Connections** - Named database connections via `.databases.json`
- **CRUD Operations** - Query, Insert, Update, Delete via MCP tools
- **Security First** - Parameterized queries, SQL injection prevention, dangerous operation blocking
- **Easy Setup** - Interactive `--init` wizard for agent configuration
- **Multi-Agent Support** - Claude Desktop, Claude Code, Cursor
- **High Performance** - Async Rust with connection pooling
## Installation
```bash
cargo install sqlx-mcp
```
Or build from source:
```bash
git clone https://github.com/epicsagas/sqlx-mcp.git
cd sqlx-mcp
cargo build --release
cp target/release/sqlx-mcp ~/.local/bin/
```
## Quick Start
### 1. Configure Databases and Agent
```bash
# Interactive setup
sqlx-mcp --init
# Or configure specific agent
sqlx-mcp --init cursor
sqlx-mcp --init claude-code
sqlx-mcp --init claude-desktop
```
### 2. Check Status
```bash
sqlx-mcp --status
```
### 3. Restart Your MCP Client
Restart Claude Desktop, Claude Code, or Cursor to load the MCP server.
> **Note**: For Claude Code, a skill is automatically installed at `~/.claude/skills/sqlx/SKILL.md`
## Configuration
### Database Configuration (`.databases.json`)
Create a `.databases.json` file in your project directory or `~/.config/sqlx-mcp/`:
```json
{
"version": "1.0",
"databases": [
{
"name": "mysql_main",
"engine": "mysql",
"host": "localhost",
"port": 3306,
"username": "root",
"password": "secret",
"database": "myapp"
},
{
"name": "postgres_analytics",
"engine": "postgres",
"host": "localhost",
"port": 5432,
"username": "postgres",
"password": "secret",
"database": "analytics"
},
{
"name": "sqlite_cache",
"engine": "sqlite",
"path": "/var/data/cache.db"
}
],
"default_connection": "mysql_main"
}
```
See `.databases.json.example` for a complete configuration example.
## Available MCP Tools
| `db_list_connections` | List all configured database connections |
| `db_query` | Execute SELECT queries, returns JSON array |
| `db_insert` | Execute INSERT, returns last_insert_id |
| `db_update` | Execute UPDATE, returns rows_affected |
| `db_delete` | Execute DELETE, returns rows_affected |
| `db_list_tables` | List all tables in database |
| `db_describe_table` | Get table structure |
| `db_health_check` | Check database connectivity |
## Usage Examples
### Natural Language Examples
The Claude Code skill allows you to use natural language to query databases:
| "Get active users from mysql_main" | Query active users from mysql_main |
| "Show recent 10 orders from postgres" | Get recent 10 orders from postgres |
| "List tables in sqlite_cache" | List all tables in sqlite_cache |
| "Describe users table structure in mydb" | Get users table schema |
| "Add new user John to mysql_main" | Insert new user John into mysql_main |
| "Delete record with id 5 from postgres" | Delete record with id 5 from postgres |
### List Connections
```json
{}
```
### Query Data
```json
{
"query": "SELECT * FROM users WHERE status = ?",
"params": ["active"],
"connection": "mysql_main"
}
```
### Query with Default Connection
```json
{
"query": "SELECT * FROM orders WHERE user_id = ?",
"params": [123]
}
```
### Insert Data
```json
{
"query": "INSERT INTO users (name, email) VALUES (?, ?)",
"params": ["John", "john@example.com"],
"connection": "postgres_analytics"
}
```
### Update Data
```json
{
"query": "UPDATE users SET status = ? WHERE id = ?",
"params": ["inactive", 5]
}
```
### Delete Data
```json
{
"query": "DELETE FROM users WHERE id = ?",
"params": [10]
}
```
### List Tables
```json
{
"connection": "sqlite_cache"
}
```
### Describe Table
```json
{
"table": "users",
"connection": "mysql_main"
}
```
## Manual Configuration
### Claude Desktop
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"sqlx": {
"command": "sqlx-mcp",
"env": {
"SQLX_MCP_CONFIG": "/path/to/.databases.json",
"RUST_LOG": "info"
}
}
}
}
```
### Claude Code
**Path**: `~/.claude.json`
```json
{
"mcpServers": {
"sqlx": {
"command": "sqlx-mcp",
"env": {
"SQLX_MCP_CONFIG": "/path/to/.databases.json",
"RUST_LOG": "info"
}
}
}
}
```
> **Note**: Project-level config can also be placed in `.mcp.json` in the project root.
### Cursor
**Path**: `~/.cursor/mcp.json`
```json
{
"mcpServers": {
"sqlx": {
"command": "sqlx-mcp",
"env": {
"SQLX_MCP_CONFIG": "/path/to/.databases.json",
"RUST_LOG": "info"
}
}
}
}
```
## Security
### Built-in Protections
- **Parameterized Queries** - All queries use `?` placeholders (auto-converted to `$1,$2,...` for PostgreSQL)
- **Query Type Validation** - SELECT for query, INSERT for insert, etc.
- **Dangerous Operations Blocked** - DROP, TRUNCATE, ALTER, CREATE, GRANT, REVOKE
- **Multi-statement Prevention** - Semicolon-separated queries blocked
- **Hidden Config File** - `.databases.json` is hidden by default for security
### Best Practices
```sql
-- Good: Use parameterized queries
SELECT * FROM users WHERE id = ?
-- Bad: Never concatenate values (blocked by design)
SELECT * FROM users WHERE id = 1; DROP TABLE users;
```
## Troubleshooting
### Connection Failed
```bash
# Check database is running
mysql -u your_user -p -h localhost your_database
psql -U your_user -h localhost your_database
# Verify configuration
sqlx-mcp --status
```
### Agent Not Detecting MCP Server
1. Restart the agent after configuration
2. Check config file path and JSON syntax
3. Verify binary is in PATH: `which sqlx-mcp`
4. Check `.databases.json` file exists and is valid
## License
Apache-2.0 License - see [LICENSE](LICENSE) for details.
## Support
If you find this project useful, consider supporting:
[](https://buymeacoffee.com/epicsaga)