db-mcp

An MCP database gateway for LLM agents: read freely, preview writes, approve explicitly.

securedblink gives an LLM a controlled, auditable way to inspect and query databases through the Model Context Protocol. Read-only work runs immediately; every mutating statement must be previewed, bound to a single-use token, and explicitly approved before it touches the database. Credentials live in your OS credential manager — never in chat history, logs, or tool responses.

Table of Contents

• About

• How it works

• Getting started

• Configure an MCP client

• What it protects

• Supported databases

• Tools

• Credential vault

• Configuration

• Source checkout

• Development

• Security

• License

Related MCP server: mcp-db-server

About

securedblink is a local MCP server that sits between your agent and your databases. You declare connections as DB_<NAME> environment variables — the suffix becomes the connection name exposed to the agent. The server classifies every statement: SELECT, EXPLAIN, SHOW/DESCRIBE, and safe WITH run through query; everything else (INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE…) is forced through the gated path.

Stack: Python 3.12+, SQLAlchemy 2.0, MCP 1.x, structlog, keyring. PostgreSQL and SQLite work out of the box; other dialects load via optional drivers.

Who it's for: engineers who want to let an agent explore schemas and run reads autonomously, but keep every write visible and reversible — ideal for analytics databases, staging environments, and local development.

How it works

Read lane — free. query executes immediately and returns rows capped by DB_MAX_ROWS (default 500).

Write lane — gated. The flow is deliberately visible:

1. Agent → preview_mutation(connection, sql)   → securedblink returns plan + one-time token
2. Agent shows preview and asks for confirmation
3. Human approves in the MCP client
4. Agent → execute_mutation(connection, sql, token) → securedblink validates token
5. securedblink executes, consumes the token, returns the result

The token binds the exact SQL string and connection name (SHA-256), expires after 5 minutes, and is single-use. A mismatched connection, altered SQL, expired token, or replay is rejected — even if the agent tries.

Vault lane — isolated. Aliases registered with securedblink register or register-from-path are stored in the OS credential manager (macOS Keychain, Linux Secret Service, Windows Credential Manager). The agent sees only the alias; values are redacted from logs and tool output.

Getting started

1. Install the command

Pick one distribution. The binary is the primary entry point for terminals and MCP clients.

macOS / Linux — standalone binary (recommended):

curl -fsSL https://raw.githubusercontent.com/paulushcgcj/securedblink/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/paulushcgcj/securedblink/main/install.ps1 | iex

PyPI / uv — all platforms (use when you need extra drivers):

uv tool install securedblink
# optional drivers
uv tool install 'securedblink[oracle]'
uv tool install 'securedblink[mysql]'
uv tool install 'securedblink[mssql]'

Standalone installers bundle PostgreSQL support only. Install via PyPI/uv tool when you need Oracle, MySQL, or MSSQL drivers.

2. Connect a database

Set one or more DB_<NAME> variables. The suffix becomes the MCP connection name.

export DB_LOCAL=sqlite:///./local.db
export DB_ANALYTICS=postgresql://user:password@db.example.com:5432/analytics
export DB_MAX_ROWS=500  # optional; defaults to 500

Prefer the credential vault for secrets (see below) rather than exporting passwords in plain text. Never commit real credentials.

3. Run it

securedblink

An MCP client can now discover local and analytics, list tables, describe schemas, and run reads. Writes will surface a preview and wait for your explicit approval.

Configure an MCP client

The binary must be on the MCP client's PATH. If it isn't, replace securedblink with its absolute path (e.g. /usr/local/bin/securedblink).

Add to ~/.config/opencode/opencode.jsonc or .opencode.json in a project:

{
  "mcp": {
    "securedblink": {
      "type": "local",
      "command": ["securedblink"],
      "environment": {
        "DB_ANALYTICS": "postgresql://user:password@host:5432/analytics",
        "DB_LOCAL": "sqlite:///./local.db",
        "DB_MAX_ROWS": "500"
      }
    }
  }
}

Add to .vscode/mcp.json or ~/.vscode/mcp.json:

{
  "servers": {
    "securedblink": {
      "type": "stdio",
      "command": "securedblink",
      "env": {
        "DB_ANALYTICS": "postgresql://user:password@host:5432/analytics",
        "DB_LOCAL": "sqlite:///./local.db",
        "DB_MAX_ROWS": "500"
      }
    }
  }
}

Keep connection values in your MCP client's environment block or in the vault. Do not commit real credentials to config files.

What it protects

Supported databases

Any SQLAlchemy-compatible dialect works once its driver is installed. PostgreSQL and SQLite need no extra setup.

Tools

Credential vault

The vault stores credentials in the platform's secure store so the agent can use an alias without ever receiving the username or password.

Register from the terminal:

securedblink register \
  --alias analytics \
  --jdbc-url "postgresql://host:5432/analytics" \
  --username user \
  --password password \
  --driver org.postgresql.Driver

securedblink list

Import from a file — allow-list the directory first:

export SECUREDBLINK_ALLOWED_ROOTS="/path/to/configs"
securedblink register-from-path \
  --alias analytics \
  --file-path /path/to/configs/analytics.env

Supported formats: .env, .properties, and Spring Boot-style .yml/.yaml. Paths outside SECUREDBLINK_ALLOWED_ROOTS are rejected; values are redacted from logs and errors.

Configuration

Source checkout

Use run.sh for development — it syncs the project, reads .env, detects drivers from DB_* URLs, and installs missing drivers before starting:

DB_LOCAL=sqlite:///./local.db ./run.sh

The installed binary does no setup preparation; configure its environment and optional drivers explicitly.

Development

Requirements: Python 3.12+ and uv.

uv sync
uv run pytest -q
uv run ruff check .
uv run mypy --strict securedblink

See CONTRIBUTING.md for the full workflow and release process.

Security

Please report vulnerabilities according to SECURITY.md. Never place real database credentials in issues, pull requests, or committed config files.

License

Distributed under GPL-3.0.