DB-MCP

Give AI assistants governed access to your databases through the Model Context Protocol. Connect any supported database, define governance rules, and let AI query your data safely.

Supported databases: PostgreSQL, MySQL, BigQuery, Snowflake, Redshift, ClickHouse

Quick Start

Demo Data (try it in 2 minutes)

git clone https://github.com/syam/db-mcp.git
cd db-mcp
docker compose up

1. Open http://localhost:3000 and click Try with Demo Data

2. The demo sets up a sample e-commerce database with cubes and governance rules pre-configured

3. Your MCP endpoint is live at http://localhost:3000/mcp/default

Add to Claude Desktop (Settings > MCP Servers):

{
  "mcpServers": {
    "db-mcp": {
      "url": "http://localhost:3000/mcp/default"
    }
  }
}

Your Own Database

git clone https://github.com/syam/db-mcp.git
cd db-mcp
cp .env.example .env   # optionally set ANTHROPIC_API_KEY for AI chat
docker compose up

1. Open http://localhost:3000 and click Add Database

2. Fill in the connection form and click Test Connection to verify

3. Generate cubes — go to the Tables page, click Generate All Cubes (or generate per-table). This creates the YAML definitions that tell the semantic layer what's queryable.

4. Configure governance (optional) — go to the Governance page to mark PII fields, control member exposure, and set query restrictions

5. Your MCP endpoint is live at http://localhost:3000/mcp/{your-database-id}

Important: Without generating cubes (step 3), MCP tools will return no data. The semantic layer automatically picks up new and changed cube files — no restart needed.

How It Works

Your Database → Cube Definitions (YAML) → Semantic Layer → Governance Rules → MCP Tools → AI Assistant

• Cube definitions map your database tables into queryable measures and dimensions

• Governance rules control which members AI can access (PII blocking, exposure, query limits)

• MCP tools expose the governed semantic layer to any MCP-compatible AI assistant

Cube Definitions

Cubes are YAML files that define what AI can query. Each cube maps a database table to typed measures (aggregations) and dimensions (attributes).

Location: data/databases/{id}/cube/model/cubes/*.yml

How to create: Use the Tables page in the admin UI and click Generate All Cubes. If you have ANTHROPIC_API_KEY set, the generator will add rich descriptions to help AI understand your data. You can also write cube YAML manually.

Example:

cubes:
  - name: orders
    sql_table: orders
    measures:
      - name: count
        type: count
      - name: total_amount
        type: sum
        sql: "{CUBE}.amount"
    dimensions:
      - name: status
        sql: "{CUBE}.status"
        type: string
      - name: created_at
        sql: "{CUBE}.created_at"
        type: time

Supported measure types: count, sum, avg, min, max, count_distinct

Supported dimension types: string, number, time, boolean

The semantic layer automatically detects new and changed cube files — no restart needed.

Governance

Governance controls which members AI can access and how. Configure via the Governance page in the admin UI, or edit data/databases/{id}/agent_catalog.yaml directly.

Example:

version: "1.0"
defaults:
  exposed: true
  pii: false
members:
  Users.email:
    exposed: false
    pii: true
  Orders.total_amount:
    allowedGroupBy:
      - Orders.status
      - Orders.created_at

Features:

• PII Protection — Mark sensitive fields to block them from all queries

• Member Exposure — Control which measures and dimensions are queryable

• Query Limits — Enforce maximum row counts per query

• Group-by Restrictions — Limit which dimensions can be used for grouping

• Default Filters — Automatically apply security filters (e.g., tenant isolation) to all queries

• Default Segments — Apply pre-defined segments to all queries

Connect to AI Assistants

Each database gets its own MCP endpoint at /mcp/{databaseId}.

Claude Desktop — Add to Settings > MCP Servers:

{
  "mcpServers": {
    "db-mcp": {
      "url": "http://localhost:3000/mcp/default"
    }
  }
}

Cursor / Other MCP Clients — Point to http://localhost:3000/mcp/{databaseId} as an HTTP MCP endpoint.

Built-in AI Chat — Set ANTHROPIC_API_KEY in your .env and use the Chat page in the admin UI to query your data conversationally.

MCP Tools

Configuration

For Docker, set these in your .env file or shell before running docker compose up:

Copy .env.example to .env to see all available variables.

Local Development

For contributors working on db-mcp itself:

# Start infrastructure with exposed ports
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d postgres cube

# Install dependencies
npm install

# Copy and edit env file
cp .env.example .env

# Start backend (port 3000)
npm run dev

# Start frontend (port 3001, in another terminal)
cd admin/frontend && npm install && npm run dev

npm run test             # Run tests
npm run lint             # Lint
npm run build            # Build for production
npx playwright test      # E2E tests

Architecture

See docs/architecture.md for detailed architecture, API reference, and troubleshooting.

localhost:3000 (nginx)
├── /api/*          Admin REST API
├── /mcp/:id        MCP endpoints (Streamable HTTP + SSE)
├── /health         Health check
└── /*              Admin UI (React SPA)
        │
        ▼
    Express Backend
        │
        ▼
    Semantic Layer (Cube.js)
        │
        ▼
    Your Databases

License

MIT