Skip to main content
Glama

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.

Related MCP server: mcp-ohmy-sql

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

Tool

Description

catalog_search

Search for measures, dimensions, and segments with fuzzy matching

catalog_describe

Get detailed member information including governance status

query_semantic

Execute governed queries against the semantic layer

Configuration

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

Variable

Required

Purpose

CUBE_JWT_SECRET

Auto-set

JWT secret shared with Cube.js (default provided in docker-compose.yml)

ANTHROPIC_API_KEY

No

Enable AI chat and LLM-enhanced cube generation

ADMIN_SECRET

No

Encrypt stored database credentials with AES-256-GCM (min 32 chars)

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

Available Tools

3 tools
catalog.describeB

Get detailed information about a specific member including its definition, type, and related members.

Inputs: member (required).

catalog.searchB

Search the data catalog for available measures, dimensions, and segments. Use this to discover what data is available for querying.

Inputs: query (required), types, cubes, limit.

query.semanticC

Execute a governed semantic query against the data warehouse. Queries are validated against governance policies before execution.

Inputs: limit (required), measures, dimensions, timeDimensions, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: catalog.describe provides detailed metadata about a specific member, catalog.search enables discovery of available data elements, and query.semantic executes governed queries. The descriptions clearly differentiate between metadata lookup, discovery, and query execution functions.

    Naming Consistency5/5

    All tools follow a consistent dot-separated naming pattern (catalog.describe, catalog.search, query.semantic) with clear verb-noun combinations. The naming convention is uniform throughout the set, making it easy to understand the tool hierarchy and relationships.

    Tool Count3/5

    With only 3 tools, the set feels somewhat thin for a database/warehouse MCP server. While the tools cover key functions (metadata, discovery, querying), typical database interfaces would include more operations like data modification, schema management, or connection handling. The count is borderline minimal but functional.

    Completeness3/5

    The tools cover discovery (search), metadata inspection (describe), and query execution, but there are notable gaps for a complete database interface. Missing are data modification operations (insert/update/delete), schema management tools, connection/configuration management, and monitoring/debugging capabilities. The surface enables read operations but lacks write capabilities.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI assistants to query and interact with SQLite databases through natural language. It includes built-in security guardrails such as PII redaction, SQL injection blocking, and query rate limiting.
      -
    • -
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that bridges AI assistants with SQL databases, enabling natural language querying across multiple database types with built-in optimization and security.
      3
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that gives AI assistants the ability to connect to, query, profile, and monitor data sources — turning any LLM into an interactive data engineering copilot.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A governed analytics MCP server that provides LLM agents with safe, read-only access to data warehouses through a layered safety pipeline including AST validation, column/row governance, PII masking, cost limits, and audit.
      MIT