DB-MCP Server

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, se