Chartbrew MCP Server

TypeScript MCP server built on the official MCP SDK for documented Chartbrew API endpoints.

Showcase

Related MCP server: metabase-mcp

Prerequisites

• Node.js and npm installed (used to install dependencies and build the server).

• A Chartbrew API key — create one in your Chartbrew account (cloud or self-hosted). See How to create API keys in Chartbrew.

• For a self-hosted Chartbrew instance, the API base URL of that instance (default http://localhost:4019).

• An MCP-compatible client to host the server (e.g. Claude Code, Claude Desktop, Cursor, VS Code, Codex, GitHub Copilot, OpenCode, Kimi Code).

Scope

This server only implements operations documented in the official Chartbrew API reference and avoids undocumented behavior.

Implemented resources:

• Teams: list, get

• Connections: list, get, test, create, update, delete

• Datasets: list, get, fetch data, create, update, delete

• Data Requests: list, run

• Dashboards (projects): list, get, create, update, delete

• Charts: get, create, query, delete

Not implemented in this version:

• Variable binding create/update endpoints

These can be added later if needed.

Authentication

Chartbrew API docs specify Bearer token authentication.

Required header used by this server:

• Authorization: Bearer

Configuration Options

Tool mode behavior:

• unrestricted: all implemented tools are available.

• restricted: only data-retrieval/query tools are available (list/get/fetch/query/run/test). Create/update/delete tools are disabled.

You can provide these values in either of two ways (pick one):

• .env file in this mcp folder — copy .env-template to .env and fill in the values. The server auto-loads it on startup.

• The env block of your coding agent's MCP config — set the variables directly in the env object of the server entry (e.g. .mcp.json for Claude Code, or the equivalent MCP config for Codex, GitHub Copilot, OpenCode, Kimi Code, etc.). Use this when you don't want a local .env file.

Install

1. Change directory to mcp.

2. Install dependencies:

   npm install

3. Build:

   npm run build

4. Run

npm start

The server uses stdio transport and is intended to be launched by an MCP client host.

Standalone binary (no Node.js required)

Prefer not to install Node.js? Download a prebuilt binary from the Releases page and run it directly. Binaries are provided for:

Setup:

Releases include both raw binaries and compressed archives (.zip for Windows, .tar.gz for Linux/macOS) — grab the archive for a smaller download, then extract it.

• Windows: download chartbrew-mcp-windows-x64.zip (or arm64), extract, run the .exe.

• macOS / Linux: download e.g. chartbrew-mcp-darwin-arm64.tar.gz, extract, then make it executable once: chmod +x chartbrew-mcp-darwin-arm64

• macOS Gatekeeper: if macOS blocks the unsigned binary, remove the quarantine attribute: xattr -d com.apple.quarantine chartbrew-mcp-darwin-arm64

You do not need a .env file — set configuration through your MCP client's env block (or the OS environment). Example for Claude Desktop / Claude Code (.mcp.json or claude_desktop_config.json):

{
  "mcpServers": {
    "chartbrew": {
      "command": "/absolute/path/to/chartbrew-mcp-darwin-arm64",
      "env": {
        "CHARTBREW_API_KEY": "your-api-key",
        "CHARTBREW_API_BASE_URL": "https://api.chartbrew.com",
        "CHARTBREW_TOOL_MODE": "restricted"
      }
    }
  }
}

Build the binaries yourself

From a checkout, install Bun (the compiler), then:

npm install
npm run build:bin   # writes binaries to dist-bin/

Full setup, Bun install commands, and the Windows cross-compile caveat are in CONTRIBUTING.md.

Add to an MCP client

After npm install and npm run build, register the server with your MCP host. The server runs over stdio via node dist/index.js. Replace <ABSOLUTE_PATH_TO_MCP_DIR> with the absolute path to this mcp directory and set your API key.

Claude Code CLI (claude mcp add)

If you use Claude Code, you can register the server directly from the terminal instead of editing a config file:

claude mcp add chartbrew \
  -e CHARTBREW_API_KEY=your-api-key \
  -e CHARTBREW_API_BASE_URL=https://api.chartbrew.com \
  -e CHARTBREW_TOOL_MODE=restricted \
  -- node <ABSOLUTE_PATH_TO_MCP_DIR>/dist/index.js

• Use http://localhost:4019 for CHARTBREW_API_BASE_URL on a self-hosted instance (change the port if yours differs).

• Add -s user (or -s project) to control the scope the server is registered in.

• Verify with claude mcp list; remove with claude mcp remove chartbrew.

Claude Desktop / Claude Code (claude_desktop_config.json or .mcp.json)

{
  "mcpServers": {
    "chartbrew": {
      "command": "node",
      "args": ["<ABSOLUTE_PATH_TO_MCP_DIR>/dist/index.js"],
      "env": {
        "CHARTBREW_API_KEY": "your-api-key",
        "CHARTBREW_API_BASE_URL": "https://api.chartbrew.com",
        "CHARTBREW_TOOL_MODE": "unrestricted"
      }
    }
  }
}

Cursor / VS Code (settings UI → MCP servers)

{
  "mcpServers": {
    "chartbrew": {
      "command": "node",
      "args": ["<ABSOLUTE_PATH_TO_MCP_DIR>/dist/index.js"],
      "env": {
        "CHARTBREW_API_KEY": "your-api-key"
      }
    }
  }
}

API base URL: use https://api.chartbrew.com for an official Chartbrew cloud account. For a self-hosted instance use your local URL — default http://localhost:4019 (change the port if yours differs).

Notes:

• CHARTBREW_API_KEY is required. See How to create API keys in Chartbrew.

• The MCP host launches the server; it does not need to be run manually.

• The default tool mode is restricted (read/query only). Set CHARTBREW_TOOL_MODE: "unrestricted" to also enable create/update/delete tools.

• Alternatively, set the env vars in a .env file in the mcp directory and omit the env block.

Available Tools

Known documentation limitations reflected in implementation

• ID types are inconsistent in docs (number vs string), so tool inputs accept strings.

• Some create/update payload required fields are not consistently documented, so payload is typed as flexible object.

• Dataset fetch filters query-object encoding is undocumented; this server sends object values as JSON strings.

• Error response schemas vary by endpoint; parser handles both error and message fields when available.