DB-MCP
DB-MCP provides governed AI access to databases through the Model Context Protocol, enabling AI assistants to safely discover and query your data.
Search the data catalog (
catalog.search): Discover available measures, dimensions, and segments by keyword; filter by cube names or member types; control result count up to 50 itemsDescribe catalog members (
catalog.describe): Get detailed definitions, types, and related members for specific data elements (e.g.,Orders.count)Execute governed semantic queries (
query.semantic): Run queries with support for measures, dimensions, time dimensions (with granularity and date ranges), filters, segments, sorting, and pagination — all automatically validated against governance policiesConnect supported databases: PostgreSQL, MySQL, BigQuery, Snowflake, Redshift, and ClickHouse
Define semantic models (cubes): Map database tables to queryable measures (count, sum, avg) and dimensions (string, number, time) via YAML definitions
Implement data governance: PII protection, member exposure controls, query/row limits, group-by restrictions, default filters, and segments
Integrate with AI assistants: Expose MCP endpoints to clients like Claude Desktop or Cursor, or use the built-in AI chat (requires Anthropic API key)
Manage via admin UI: Add databases, generate cubes, configure governance, and monitor connections
Provides governed access to ClickHouse databases, allowing AI agents to search data catalogs, describe table schemas, and execute semantic queries.
Provides governed access to MySQL databases, allowing AI agents to search data catalogs, describe table schemas, and execute semantic queries.
Provides governed access to PostgreSQL databases, allowing AI agents to search data catalogs, describe table schemas, and execute semantic queries.
Provides governed access to Snowflake data warehouses, allowing AI agents to search data catalogs, describe table schemas, and execute semantic queries.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@DB-MCP What was the total revenue by region for the last quarter?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 upOpen http://localhost:3000 and click Try with Demo Data
The demo sets up a sample e-commerce database with cubes and governance rules pre-configured
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 upOpen http://localhost:3000 and click Add Database
Fill in the connection form and click Test Connection to verify
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.
Configure governance (optional) — go to the Governance page to mark PII fields, control member exposure, and set query restrictions
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 AssistantCube 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: timeSupported 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_atFeatures:
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 |
| Search for measures, dimensions, and segments with fuzzy matching |
| Get detailed member information including governance status |
| 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 |
| Auto-set | JWT secret shared with Cube.js (default provided in docker-compose.yml) |
| No | Enable AI chat and LLM-enhanced cube generation |
| 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 devnpm run test # Run tests
npm run lint # Lint
npm run build # Build for production
npx playwright test # E2E testsArchitecture
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 DatabasesLicense
MIT
Available Tools
3 toolscatalog.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
Scored across 3 tools
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.
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.
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.
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
Related MCP Connectors
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
The BigQuery remote MCP server is a fully managed service that uses the Model Context Protocol to connect AI applications and LLMs to BigQuery data sources. It provides secure, standardized tools for AI agents to list datasets and tables, retrieve schemas, generate and execute SQL queries through natural language, and analyze data—enabling direct access to enterprise analytics data without requiring manual SQL coding.
Cloud-hosted MCP server for secure AI access to enterprise data sources via CData Connect AI.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn 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.-
- -licenseNot gradedqualityDmaintenanceAn MCP server that bridges AI assistants with SQL databases, enabling natural language querying across multiple database types with built-in optimization and security.3-
- AlicenseNot gradedqualityDmaintenanceAn 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
- AlicenseNot gradedqualityDmaintenanceA 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