db-mcp

Your teams are copy-pasting company data into Claude. Give them a safe way to do it.

db-mcp is an open-source MCP server that connects Claude Desktop to your databases—with a self-improving semantic layer that gets smarter with every query.

No infrastructure needed. Runs locally. Data never leaves your network.

Installation

curl -fsSL https://download.apelogic.ai/db-mcp/install.sh | sh

Why db-mcp?

• Ask Claude, get answers — Stop waiting for reports. Query your data in natural language without SQL, copy-pasting schemas, or context-setting
• Self-improving semantic layer — Auto-generates descriptions of your schema, then learns from every query to improve accuracy over time
• Runs on your desktop — No cloud infrastructure, no data leaving your network. Uses your existing database credentials and access controls
• Git-style collaboration — Data teams review and approve semantic layer improvements. You stay in control, users get accurate answers
• Open source & auditable — MIT licensed, fully transparent, no vendor lock-in

Who is db-mcp for?

How It Works

From install to insight in four steps:

1. Install — Download db-mcp to your laptop. No infrastructure needed—runs locally in minutes
2. Connect — Add data sources using your existing credentials. Your security posture stays intact
3. Query — Ask Claude questions across your connected data. Every query is validated before execution
4. Improve — The semantic layer learns from usage. Review and approve improvements with a git-style workflow

Quick Start

# Configure your database and Claude Desktop
db-mcp init

# Check configuration
db-mcp status

Supported Agents

Claude Desktop

The default setup works with Claude Desktop. Follow the Quick Start instructions above.

OpenClaw

db-mcp works with OpenClaw via mcporter:

# Install mcporter (MCP bridge for OpenClaw)
npm i -g mcporter

# Configure db-mcp for OpenClaw
db-mcp init

Or manually add to ~/.openclaw/workspace/config/mcporter.json:

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

Supported Databases

• PostgreSQL
• ClickHouse
• Trino
• MySQL
• SQL Server

Security & Governance

• Runs locally — Data stays on your machine, never routed through external servers
• Read-only by default — Query validation and cost guards prevent accidental data modification
• Uses existing RBAC — Connects with your database credentials and respects your access controls
• Full audit trail — Complete interaction history for compliance and debugging
• Open source — Fully auditable, MIT licensed

Commands

Setup & Configuration

Connection Management

Server & Diagnostics

Git Sync (Team Collaboration)

Migration

Configuration

Connection data is stored in ~/.db-mcp/:

~/.db-mcp/
├── config.yaml                      # Global config, active connection
└── connections/{name}/
    ├── .env                         # Database credentials (gitignored)
    ├── state.yaml                   # Onboarding state
    ├── schema/
    │   └── descriptions.yaml        # Table/column descriptions
    ├── domain/
    │   └── model.md                 # Domain model documentation
    ├── training/
    │   ├── examples.yaml            # Query examples (NL → SQL mappings)
    │   └── instructions.yaml        # Custom SQL generation rules
    └── .git/                        # Optional git sync for team sharing

Configuration Artifacts

Environment Variables

Development

# Clone
git clone https://github.com/apelogic-ai/db-mcp.git
cd db-mcp

# Install dependencies
uv sync

# Run locally
cd packages/core
uv run db-mcp --help

# Lint
cd packages/core && uv run ruff check . --fix
cd packages/ui && bun run lint

# Build binary
cd packages/core
uv run python scripts/build.py

Testing

93 tests across three layers:

# Python unit tests (49 tests)
cd packages/core
uv run pytest tests/ -v

# UI unit tests (20 tests)
cd packages/ui
bun run test

# UI E2E tests (24 tests)
cd packages/ui
bunx playwright test

All tests run in CI via GitHub Actions on every push and PR. See docs/testing.md for the full testing guide.

Tool Coverage Check

Verify that 100% of MCP tools implemented in the codebase are exposed by the MCP server at runtime:

# Run the tool coverage audit (default SQL mode)
python scripts/tool_coverage_audit.py

# Test different configuration modes
python scripts/tool_coverage_audit.py --config api
python scripts/tool_coverage_audit.py --config shell
python scripts/tool_coverage_audit.py --config metabase

# Verbose output with all tool names
python scripts/tool_coverage_audit.py --verbose

# JSON output for CI integration
python scripts/tool_coverage_audit.py --json

The audit returns exit code 0 on success (100% coverage) and 1 on failure.

Project Structure

db-mcp/
├── packages/
│   ├── core/                # Main application (db-mcp)
│   ├── models/              # Shared Pydantic models (db-mcp-models)
│   └── ui/                  # Next.js control plane UI
├── docs/                    # Design documents
├── scripts/                 # Installation scripts
└── .github/workflows/       # CI/CD

Roadmap

See docs/ for design documents on planned features:

• Metrics Layer - Semantic metric definitions (DAU, revenue, etc.)
• Desktop App - Electron GUI with visual query builder
• Knowledge Extraction - Learn from query traces automatically
• Data Gateway - Unified access to multiple data sources

Resources

• GitHub
• Discord Community
• Report Issues

License

MIT