Configuring dbt charts MCP Server
Set up the dbt charts MCP server to give AI assistants access to dashboard tools and resources.
This skill is CLI-only (
surfaces: [cli]) — it walks a human operator through installing the MCP server from a shell. An already-connected MCP agent does not need to read it.
Quick Setup
The fastest way — auto-detects your AI clients and configures them:
pip install "dbt-charts[mcp]"
dct init mcp
This detects Cursor, VS Code, Claude Desktop, Claude Code, Copilot, and Codex, then writes the appropriate config files.
Target a Specific Client
dct init mcp cursor # Configure Cursor only
dct init mcp vscode # Configure VS Code only
dct init mcp claude # Configure Claude Desktop only
dct init mcp claude-code # Configure Claude Code only
dct init mcp codex # Configure Codex CLI only
dct init mcp copilot # Configure GitHub Copilot Coding Agent only
dct init mcp --all # Write every supported config file
dct init mcp print # Print JSON config to stdout (manual setup)
Force Update
dct init mcp cursor -f # Overwrite existing config
After running dct init mcp, restart your AI client for changes to take effect.
Manual Configuration
If you prefer manual setup, add this to your client's MCP config.
For JSON-based clients (Cursor, VS Code, Claude Desktop, Claude Code, Copilot):
{
"mcpServers": {
"dbt-charts": {
"command": "/path/to/dct",
"args": ["mcp", "serve"]
}
}
}
For Codex (TOML — .codex/config.toml):
[mcp_servers.dbt-charts]
command = "/path/to/dct"
args = ["mcp", "serve"]
If your dbt charts or dbt project lives in a subdirectory of the workspace your
AI client opens (or the server otherwise won't be launched with cwd at the
project root), append "--project-dir", "/abs/path/to/your/project" to args.
dct init mcp will add this for you when its --project-dir flag is used or
when it detects that the workspace and project roots diverge.
Config file locations:
- Cursor:
.cursor/mcp.json - VS Code / Copilot agent mode:
.vscode/mcp.jsonwith aserversroot key - Claude Desktop:
~/.config/claude/config.json - Claude Code:
.mcp.jsonat the project root - Codex:
.codex/config.toml(project must be trusted by Codex) — globally,~/.codex/config.toml - GitHub Copilot Coding Agent:
.github/copilot/mcp.jsonwith aserversroot key
Use the absolute path to dct in the command field. Find it with which dct.
Available Tools
After setup, your AI assistant has access to these tools:
| Tool | Purpose |
|---|---|
render_board |
Compile, execute queries, and generate visual HTML/text output |
execute_sql |
Run ad-hoc SQL, SQL as a query of a saved board, or one named board query, and inspect columns/sample rows |
find_queries |
Find the boards and queries that answer a question, with each query's columns, variables and cached rows (how fresh); execute_sql(board=…, sql=…) then reads cached rows with {{ queries.NAME.cache }} and no warehouse call; needs DCT_CACHE_PATH set for dct mcp serve |
list_skills / get_skill |
Discover and read packaged dbt charts authoring skills — get_skill returns the full body including example YAML |
Available Resources
| Resource | Content |
|---|---|
dct://guide/chart |
Board and chart grammar, build-render-fix loop |
dct://guide/report-design |
Report design principles and narrative structure |
dct://boards |
List of all dashboards in the project |
dct://board/{path} |
YAML content and compiled structure of a specific dashboard |
Troubleshooting
"MCP server requires additional dependencies"
Install the MCP extras:
pip install "dbt-charts[mcp]"
MCP server not starting
- Verify
dctis accessible:which dct - Ensure the path in MCP config is absolute, not relative
- Check that your Python environment has
dbt-charts[mcp]installed - Try running
dct mcp servemanually to see error output
"No AI client directories detected"
dct init mcp looks for .cursor/, .codex/, .vscode/, .github/, CLAUDE.md, AGENTS.md, or ~/.config/claude/ to auto-detect clients. If none exist yet, specify the client explicitly:
dct init mcp cursor
Tools not appearing in AI client
- Restart the AI client after running
dct init mcp - Verify the config file was written: check
.cursor/mcp.jsonor equivalent - Ensure the
commandpath in the config points to the correctdctbinary
Verifying the Setup
After configuration, test by asking your AI assistant:
- "List available data sources" → should invoke
schema(no args) - "Show me the database schema" → should invoke
schema(source=...) - "Render this dashboard YAML file" → should invoke
render_board
If the assistant doesn't recognize these tools, the MCP server isn't connected — check the Troubleshooting steps above.
