sqlx-mcp

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

cargo install sqlx-mcp

Or build from source:

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

# 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

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/:

{
  "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

Tool	Description
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:

Request	Description
"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

{}

Query Data

{
  "query": "SELECT * FROM users WHERE status = ?",
  "params": ["active"],
  "connection": "mysql_main"
}

Query with Default Connection

{
  "query": "SELECT * FROM orders WHERE user_id = ?",
  "params": [123]
}

Insert Data

{
  "query": "INSERT INTO users (name, email) VALUES (?, ?)",
  "params": ["John", "john@example.com"],
  "connection": "postgres_analytics"
}

Update Data

{
  "query": "UPDATE users SET status = ? WHERE id = ?",
  "params": ["inactive", 5]
}

Delete Data

{
  "query": "DELETE FROM users WHERE id = ?",
  "params": [10]
}

List Tables

{
  "connection": "sqlite_cache"
}

Describe Table

{
  "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

{
  "mcpServers": {
    "sqlx": {
      "command": "sqlx-mcp",
      "env": {
        "SQLX_MCP_CONFIG": "/path/to/.databases.json",
        "RUST_LOG": "info"
      }
    }
  }
}

Claude Code

Path: ~/.claude.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

{
  "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

-- 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

# 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 for details.

Support

If you find this project useful, consider supporting: