RBDC MCP Server

A database server based on Model Context Protocol (MCP), supporting SQLite, MySQL, PostgreSQL, MSSQL, DuckDB, and Turso databases.

🇨🇳 中文文档 / Chinese Documentation: readme_cn.md

Advantages

• Multiple Database Support: Seamlessly work with SQLite, MySQL, PostgreSQL, MSSQL, DuckDB, and Turso using a unified interface
• AI Integration: Native integration with Claude AI through the Model Context Protocol
• Zero Configuration: Automatic management of database connections and resources
• Security: Controlled access to your database through AI-driven natural language queries
• Simplicity: Use natural language to query and modify your database without writing SQL

Installation

🚀 Method 1: Install via Cargo (Recommended)

Prerequisites: Install Rust first.

Choose the install command based on your needs:

# All drivers (default, ~10-15 minutes build)
cargo install --git https://github.com/rbatis/rbdc-mcp.git

# Minimal: SQLite only (fastest build, ~2-3 minutes)
cargo install --git https://github.com/rbatis/rbdc-mcp.git --no-default-features --features sqlite

# Single driver (e.g., MySQL):
cargo install --git https://github.com/rbatis/rbdc-mcp.git --no-default-features --features mysql

# Multiple drivers:
cargo install --git https://github.com/rbatis/rbdc-mcp.git --no-default-features --features "mysql postgres"

💡 Build speed tip: If you only need one database (e.g., SQLite), add `--no-default-features --features sqlite` to skip compiling unused drivers, cutting build time from ~15 minutes to ~2 minutes.

Available Features

📦 Method 2: Download Pre-built Binaries

Download the latest release for your platform from GitHub Releases:

After downloading, rename the file to `rbdc-mcp` (or `rbdc-mcp.exe` on Windows) and add it to your system PATH.

🔧 Agent Client Configuration

Configure rbdc-mcp in your MCP-compatible client by adding it to the MCP server list.

Claude Desktop

Configuration File Location:

• Windows: `%APPDATA%\Claude\claude_desktop_config.json`
• macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

Basic Configuration:

{
  "mcpServers": {
    "rbdc-mcp": {
      "command": "rbdc-mcp",
      "args": []
    }
  }
}

With `args: []`, the server starts with no database pre-configured.

The AI registers databases at runtime using the `add_database` tool (see

Dynamic Multi-Database below).

To pre-configure a database at startup:

{
  "mcpServers": {
    "rbdc-mcp": {
      "command": "rbdc-mcp",
      "args": ["--database-url", "sqlite://./database.db"]
    }
  }
}

Database Examples:

Single-Server Multi-Database Configuration

One `rbdc-mcp` process can host many databases. The first `--database-url` is registered as the `default` alias; pair extra URLs with `--alias` to declare a fixed set the AI can see immediately at startup via `list_databases` (see ). The AI can also register more databases at runtime through the `add_database` MCP tool.

Start a single `default` database (AI registers the rest at runtime):

{
  "mcpServers": {
    "rbdc-mcp": {
      "command": "rbdc-mcp",
      "args": [
        "--database-url", "sqlite://./database.db"
      ]
    }
  }
}

Pre-declare several databases with explicit aliases (one process, multiple pools):

{
  "mcpServers": {
    "rbdc-mcp": {
      "command": "rbdc-mcp",
      "args": [
        "--database-url", "sqlite://./local.db",                    "--alias", "local",
        "--database-url", "mysql://user:password@db1:3306/orders",  "--alias", "orders",
        "--database-url", "postgres://user:password@db2:5432/bi",   "--alias", "bi",
        "--database-url", "duckdb://./warehouse.duckdb",             "--alias", "warehouse"
      ]
    }
  }
}

The first `--alias` value is ignored (the first URL always becomes `default`). The aliases must be unique, non-empty, and not equal to `default` for any URL after the first.

Legacy style — one process per database (still works, but no longer needed for multi-database access):

{
  "mcpServers": {
    "rbdc-mcp-sqlite": {
      "command": "rbdc-mcp",
      "args": ["--database-url", "sqlite://./database.db"]
    },
    "rbdc-mcp-mysql": {
      "command": "rbdc-mcp",
      "args": ["--database-url", "mysql://user:password@localhost:3306/database"]
    },
    "rbdc-mcp-postgres": {
      "command": "rbdc-mcp",
      "args": ["--database-url", "postgres://user:password@localhost:5432/database"]
    },
    "rbdc-mcp-mssql": {
      "command": "rbdc-mcp",
      "args": ["--database-url", "mssql://user:password@localhost:1433/database"]
    },
    "rbdc-mcp-duckdb": {
      "command": "rbdc-mcp",
      "args": ["--database-url", "duckdb://path/to/database.duckdb"]
    },
    "rbdc-mcp-turso": {
      "command": "rbdc-mcp",
      "args": ["--database-url", "turso://database-url?token=your-token"]
    }
  }
}

Windows Full Path (if not in PATH)

{
  "mcpServers": {
    "rbdc-mcp": {
      "command": "C:\\tools\\rbdc-mcp.exe",
      "args": ["--database-url", "sqlite://C:\\path\\to\\database.db"]
    }
  }
}

Restart: After saving, restart Claude Desktop to load the MCP server.

Test: In Claude Desktop, try asking:

• "Show me the database connection status"
• "What tables are in my database?"

Codex

Configuration File Location:

• Global: `~/.codex/mcp.toml`
• Project-level: `.codex/mcp.toml` (place in your project root)

Basic Configuration (`.codex/mcp.toml` or `~/.codex/mcp.toml`):

[mcp_servers.rbdc-mcp]
command = "rbdc-mcp"
args = ["--database-url", "sqlite://./database.db"]
type = "stdio"
enabled = true

Database Examples (single process, multiple databases):

# Pre-declare several databases with explicit aliases
[mcp_servers.rbdc-mcp]
command = "rbdc-mcp"
args = [
  "--database-url", "sqlite://./local.db",                    "--alias", "local",
  "--database-url", "mysql://user:password@db1:3306/orders",  "--alias", "orders",
  "--database-url", "postgres://user:password@db2:5432/bi",   "--alias", "bi",
  "--database-url", "duckdb://./warehouse.duckdb",            "--alias", "warehouse",
]
type = "stdio"
enabled = true

The first URL becomes the `default` alias (its `--alias`, if any, is ignored). Additional URLs must be paired with `--alias` in declaration order. The AI can see every registered alias at startup through the `list_databases` MCP tool, and can also register more databases at runtime through `add_database`.

Restart: After saving the config file, restart Codex to load the MCP server. If Codex is already running, run `codex reconnect` to force a reload.

Test: In Codex chat, try asking:

• "Show me the database connection status"
• "What tables are in my database?"

📊 Usage Examples

Natural Language Database Operations

• Query Data: "Show me all users in the database"
• Modify Data: "Add a new user named John with email john@example.com"
• Get Status: "What's the database connection status?"
• Schema Info: "What tables exist in my database?"
• Multi-Database: "Connect to my MySQL orders database and compare its row counts with the local SQLite cache"

🗄️ Database Support

⚙️ Configuration Options

🛠️ Available Tools

• `sql_query`: Execute a single read-only SQL statement. Pass optional `alias` to target a non-default database; defaults to `default`.
• `sql_exec`: Execute INSERT/UPDATE/DELETE operations when the server is not in read-only mode. Pass optional `alias` to target a non-default database.
• `db_status`: Inspect connection pool state for a database. Pass optional `alias`.
• `test_connection`: Ping a registered database. Pass optional `alias`.
• `list_databases`: List all registered database aliases along with their URL and detected type.
• `add_database`: Register a new database connection under an `alias` and start a pool at runtime. Supported URL schemes: `sqlite://`, `mysql://`, `pg://` / `postgres://`, `mssql://` / `sqlserver://`, `duckdb://`, `turso://` / `libsql://`.
• `remove_database`: Unregister a previously-added alias. The reserved `default` alias cannot be removed.

🔌 Dynamic Multi-Database

`rbdc-mcp` is a multi-database server from a single process. You can start

it with no database URL at all (`args: []` in your MCP client config) and

let the AI register databases on the fly through MCP tools. When a URL is

provided via `--database-url`, it becomes the `default` alias; the AI can then

register more databases at runtime and route queries to any of them by `alias`.

Zero-URL Startup (Dynamic Mode)

When the server starts with no `--database-url`, the `list_databases` tool

returns an empty list and any operation targeting the `default` alias will

suggest using `add_database` first. The AI can register the first (or any)

database under any alias it chooses:

1. `add_database(alias="inventory", url="sqlite://./inventory.db")` — register

a database.

2. `list_databases` — confirm it is now registered.

3. `sql_query({ alias: "inventory", sql: "SELECT * FROM products" })` — query it.

> Tip: You can also register a database with `alias="default"` if you

> prefer to omit `alias` from subsequent queries.

Pre-declared Startup (Static Mode)

Tool flow the AI follows:

1. `list_databases` — see all currently registered aliases.

2. `add_database(alias="orders_mysql", url="mysql://user:pass@host/orders")` — register a new database and start a pool for it.

3. `sql_query({ alias: "orders_mysql", sql: "SELECT COUNT(*) FROM orders" })` — route a query to that database. Omit `alias` to use the `default` one.

4. `remove_database(alias="orders_mysql")` — tear down the pool and unregister the alias when finished.

Two ways to register databases

Both paths write into the same in-memory `alias → pool` registry, so the result is identical from the AI's point of view: `list_databases` returns every alias regardless of where it was registered.

Why this matters

• One MCP server process, many databases — no need to spawn `rbdc-mcp-mysql`, `rbdc-mcp-postgres`, etc. for each database.
• All aliases are discoverable via `list_databases`, so the AI can dynamically pick the right target per query.
• When a `--database-url` is provided, the `default` alias is reserved for it and cannot be removed.
• Each alias has its own independent connection pool — concurrent queries against different aliases do not block each other.

Example prompt you can give the AI

> "Connect to my MySQL orders database at `mysql://root:pwd@10.0.0.5/orders` and tell me the total revenue by month."

The AI will call `add_database(...)`, then `sql_query(...)` against that alias

without restarting the MCP server — works the same whether you provided a

`--database-url` at startup or not.

Read-Only Mode

`--read-only` disables the `sql_exec` tool, preventing any data modifications. Additionally, `sql_query` validates submitted SQL and rejects statements containing write keywords (INSERT, UPDATE, DELETE, etc.) or multi-statement input.

📸 Screenshots

Step 1: Configuration

Step 2: Usage in Claude

License

Apache-2.0

• Multi-Database in One Server: The AI can register additional database connections at runtime via the `add_database` tool and route queries to any registered database by its `alias` — no need to spawn extra MCP server processes

| `--database-url, -d` | Database connection URL. Omit to start empty (databases added at runtime via `add_database`). Repeat to pre-register multiple databases at startup. | `None` (optional) |