Skip to content

dct mcp

You may be looking for the Claude & ChatGPT connector

To use dbt Charts from the Claude or ChatGPT app, add the hosted connector, https://dbtcharts.com/mcp: see Claude & ChatGPT connector. It signs you in to dbt Charts Cloud and needs no CLI, no git checkout, and no coding agent. dct mcp serve is not that.

dct mcp serve runs a local MCP server over stdio, against a project on your own machine. It has a few use cases:

  • Editor agents without a shell, such as VS Code / GitHub Copilot agent mode, editing a local checkout. The editor extension wires it up for you.
  • Data that stays on your machine, such as a local DuckDB file, used from an MCP-only client.
  • The open-source engine with no dbt Charts Cloud account.

If your agent can run shell commands (Claude Code, Codex, Cursor), prefer the dct CLI and its skills over this server; the CLI is also the tool for admin work, through dct cloud. See CLI and MCP for AI assistants for the full comparison.

dct mcp [OPTIONS] COMMAND [ARGS]

Subcommands

Command Purpose
dct mcp serve Start the MCP server for AI assistant integration.

dct mcp serve

Starts a local MCP server that lets an MCP client on your machine interact with your dbt Charts project. The server runs in stdio mode, the standard transport for MCP-compatible tools.

dct mcp serve [OPTIONS]

Options

Flag Description
--project-dir PATH dbt Charts or dbt project directory. Default: current directory.

Examples

dct mcp serve
dct mcp serve --project-dir ./my-project

Manual client configuration

In most cases, dct init mcp writes the right config for you. For manual setup of Claude Code (~/.config/claude/config.json) or Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "dbt-charts": {
      "command": "dct",
      "args": ["mcp", "serve"]
    }
  }
}

For a nested project directory:

{
  "mcpServers": {
    "dbt-charts": {
      "command": "dct",
      "args": ["mcp", "serve", "--project-dir", "/absolute/path/to/project"]
    }
  }
}

What the MCP server exposes

CLI verbs wrapped as MCP tools that agents call directly:

Board authoring

  • render_board: compile, validate, and produce SVG / HTML / PNG / PDF
  • describe_board: describe a dashboard's queries, charts, variables, and layout

Data discovery

  • search_files: keyword search across board files (no text lists them all), or the project's meta.yml, dbt model, and config files with kind

Query inspection

  • execute_sql: run raw SQL (sql), or one named query from a board file (board + query), and return the result as CSV. There is no row-limit argument: the AI writes LIMIT and OFFSET in the SQL. Results are bounded at about 25,000 tokens; a cut result says so and how to narrow the query

Agent skills

  • list_skills: enumerate packaged agent skill recipes
  • get_skill: read a specific skill

Diagnostic code lookup

  • list_diagnostic_codes: list every registered error/warning code with a one-line summary, optionally filtered by level
  • get_diagnostic_code: full documentation for one error or warning code

See dct skills for the agent-facing skill catalog that ships alongside.

Resources

Beyond tools, the MCP server exposes read-only dct:// resources: content an assistant can fetch by URI without a tool call:

Resource Content
dct://boards List of all dashboards in the project with metadata
dct://board/{path} YAML content and compiled structure of one dashboard
dct://guide/chart Board and chart grammar, and the build-render-fix loop
dct://guide/report-design Design principles for narrative, data-driven reports

The server runs every query fresh unless DCT_CACHE_PATH is set; with it set, query results are cached in that DuckDB file. Unlike dct render and dct serve, it does not use the per-user cache file by default.