DB-MCP

DB MCP Gateway

Give Claude Code, Cursor, Windsurf, or any MCP-compatible AI tool read-only access to your databases — without exposing credentials or risking data changes.

Self-hosted. Everything runs locally. Your passwords never leave your machine.

https://github.com/user-attachments/assets/f768ff6f-3c9e-4583-9179-c7022d3b7487

Supported databases

	Database	Notes
	PostgreSQL	All versions
	MySQL	MySQL 5.7+ / MariaDB
	SQLite	Local file, no server needed
	Amazon Redshift	SSL required, Redshift-specific catalog queries

---

What it does

Instead of copy-pasting query results between your DB client and your AI tool, the gateway lets your AI query the database directly. It can explore schemas, inspect tables, and run SELECT queries. It cannot insert, update, delete, or drop anything.

---

Quick Start

Option A — Docker (recommended, no local install needed)

git clone https://github.com/mdadul/db-mcp
cd db-mcp

# Generate .env with secure random keys, then start
sh scripts/setup.sh
docker compose up

docker compose pulls the pre-built image from Docker Hub — no build step required.
The MCP_TOKEN is printed by setup.sh — copy it before you close the terminal.

---

Option B — Native (requires Bun)

git clone https://github.com/mdadul/db-mcp
cd db-mcp
bun install
bun run dev   # generates .env automatically, then starts the server

Open http://localhost:4080.
Your MCP_TOKEN is in .env.

---

Connect your AI tool

Claude Code (CLI)

claude mcp add --transport http db-mcp http://localhost:4080/mcp \
  --header "Authorization: Bearer <MCP_TOKEN>"

Then restart Claude Code.

Cursor / Windsurf / Claude Desktop

Add to your mcp.json:

{
  "mcpServers": {
    "db-mcp": {
      "url": "http://localhost:4080/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_TOKEN>"
      }
    }
  }
}

Claude.ai Web

Claude.ai requires HTTPS. Expose the gateway through a tunnel first:

# Option A — Cloudflare (no account needed)
npx cloudflared tunnel --url http://localhost:4080

# Option B — ngrok
ngrok http 4080

Copy the https://... URL from the tunnel output, then add it in Claude.ai → Settings → Integrations → Add MCP Server.

---

Using it with your AI

Once connected, just ask naturally:

"How many orders were created this week?" "What columns does the users table have?" "Show me the last 10 failed jobs."

The AI will call the gateway tools automatically — no copy-pasting.

Available tools

Tool	What it does
list_databases	Lists all connected databases
get_database_schema	Lists tables (optional name filter)
get_table_schema	Shows columns, indexes, and foreign keys for a table
execute_read_query	Runs a SELECT query (capped at 100 rows by default, max 1000)

---

Environment variables

Variable	Required	Description
DATABASE_PATH	Yes	Path for the local SQLite metadata store (e.g. ./data/db-mcp.sqlite)
ENCRYPTION_KEY	Yes	64-char hex key for credential encryption. Generate: openssl rand -hex 32
MCP_TOKEN	Yes	Bearer token for the /mcp endpoint. Generate: openssl rand -base64 32
PORT	No	HTTP port (default: 4080)

A .env file is created with generated values on first run.

---

Troubleshooting

Tools not showing up in Claude Code Restart Claude Code after adding the MCP server. If still missing, run claude mcp list to confirm it's registered and shows ✓ Connected.

"Failed to connect" in Claude Code Check the gateway is running (http://localhost:4080 should load) and the token in your config matches .env.

"Session not found" errors The gateway is stateless — each request is independent. If you see this, reconnect the MCP server in your IDE.

"URL must start with https" (Claude.ai Web) Claude.ai blocks plain HTTP. Use a tunnel — see the Claude.ai Web setup above.

Connection refused to my database If the gateway runs in Docker and your database is on the host, use host.docker.internal instead of localhost as the host.

---

Security notes

• The MCP_TOKEN controls access to all your databases via the gateway. Treat it like a password.
• Database credentials are encrypted with AES-256-GCM. The key lives only in ENCRYPTION_KEY — never in the database.
• Only SELECT, SHOW, DESCRIBE, and EXPLAIN are permitted. Write operations are rejected at the gateway layer before reaching the database.
• All queries are logged in the web dashboard under each database's Logs tab.