mcp server

badger-db-mcp

Badger DB MCP — minimal, token-efficient Database MCP Server for PostgreSQL, MySQL, SQL Server, SQLite, MariaDB

ajgreyling/badger-db-mcpcommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

Node.js 20 or newer

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "badger-db-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "badger-db-mcp"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 23, 2026

Badger DB MCP

Badger DB MCP is a token-efficient MCP server for exploring and querying SQL databases from MCP-capable clients.

Purpose

Expose database access through MCP tools.
Support PostgreSQL databases.
Provide safe defaults (read-only unless explicitly enabled for destructive SQL).

Repository Landmarks

src/index.ts - entrypoint and startup path.
src/server.ts - HTTP MCP transport wiring.
src/connectors/ - database connector implementations.
src/tools/ - MCP tool handlers (execute_sql, search_objects).
src/config/ - TOML/config loading and validation.
frontend/ - local web workbench UI.
CLAUDE.md - architecture and development conventions.

Quick Start

pnpm install
pnpm run dev

Build and test:

pnpm run build
pnpm test

MCP Request Flow

flowchart LR
    A[MCP Client] --> B[Transport: stdio or HTTP]
    B --> C[Tool Router]
    C --> D{Tool}
    D -->|execute_sql| E[Connector Manager]
    D -->|search_objects| E
    E --> F[Database Connector]
    F --> G[(Database)]
    G --> F --> E --> C --> A

Query Execution State Machine

stateDiagram-v2
    [*] --> RequestReceived
    RequestReceived --> ValidatingInput
    ValidatingInput --> SelectingSource
    SelectingSource --> Executing
    Executing --> FormattingResponse
    FormattingResponse --> Completed
    Executing --> Failed
    ValidatingInput --> Failed
    Failed --> [*]
    Completed --> [*]

Human + AI Agent Onboarding Checklist

Read CLAUDE.md before editing connectors/tools.
Prefer tool-level changes in src/tools/ over transport-layer changes.
Keep source_id routing behavior backward compatible.
Run relevant tests (pnpm test, or targeted connector/integration tests).

Tool Schema Examples

execute_sql input:

{
  "sql": "SELECT id, email FROM users LIMIT 10;"
}

search_objects input:

{
  "object_type": "column",
  "schema": "public",
  "table": "users",
  "pattern": "%_id",
  "detail_level": "summary",
  "limit": 50
}

Related Docs

docs/ for user-facing documentation.
dbhub.toml.example for multi-source configuration examples.