Install the CLI - Chatblocks

The CLI ships as a single npm package, @chatblocks/cli. It includes two binaries:

chatblocks — terminal CLI for common operations (list / get / create on blocks, canvases, data sources, schedules).
chatblocks-mcp — stdio MCP server that proxies to the hosted /api/mcp/v1 endpoint. Use it from any MCP client that only speaks stdio (Claude Desktop, some IDE plugins).

Both binaries are HTTPS clients against the hosted MCP server. There’s no Convex dep, no internal SDK — just a pure JSON-RPC client.

Install

pnpm i -g @chatblocks/cli

npm i -g @chatblocks/cli

bun add -g @chatblocks/cli

yarn global add @chatblocks/cli

Verify:

chatblocks --version
chatblocks-mcp --help

Node 20+ is required.

Log in

chatblocks login

You’ll be prompted for an API key and (optionally) a base URL. The CLI validates the key by calling workspace.get against the MCP endpoint before saving — if your key is wrong, you’ll know immediately.

API key (cb_live_...): cb_live_...
Base URL [https://chatblocks.ai/api/mcp/v1]:
Logged in to workspace: My Workspace (builder)

You can also pass flags non-interactively:

chatblocks login --api-key cb_live_... --base-url https://chatblocks.ai/api/mcp/v1

Config is written to ~/.chatblocks/config.json with file mode 0600. Fields:

{
  "apiKey": "cb_live_...",
  "baseUrl": "https://chatblocks.ai/api/mcp/v1"
}

Need to point at a non-default endpoint (e.g. a Convex dev deploy)? Set CHATBLOCKS_BASE_URL in your shell. It overrides the stored baseUrl per invocation — handy for testing without re-running login.

Verify

chatblocks whoami

Prints the workspace name, plan, the first 12 chars of the key, and the resolved base URL.

chatblocks logout

Removes ~/.chatblocks/config.json.

Use `chatblocks-mcp` from Claude Desktop

Claude Desktop only speaks stdio, so use the proxy. After chatblocks login succeeds, add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the Windows equivalent:

{
  "mcpServers": {
    "chatblocks": {
      "command": "chatblocks-mcp"
    }
  }
}

Restart Claude Desktop. The proxy reads the same ~/.chatblocks/config.json the CLI uses, forwards tools/list and tools/call over HTTPS, and pipes the result back to stdio.

Streaming tools (blocks.create, blocks.build, dataSources.testConnection, dataSources.triggerRefresh, schedule.preview) work through the proxy, but only the final result reaches the stdio client today — intermediate progress notifications aren’t bridged. For real-time progress, use the HTTP transport directly.

Update

The CLI is a regular npm package. To update:

pnpm up -g @chatblocks/cli

Or whichever global-update incantation your package manager uses.

What’s next

Commands

Full command reference — blocks, canvases, data sources, schedule, auth.

MCP setup

The hosted MCP endpoint behind everything in the CLI.

​Install

​Log in

​Verify

​Use chatblocks-mcp from Claude Desktop

​Update

​What’s next

Commands

MCP setup

Install

Log in

Verify

Use `chatblocks-mcp` from Claude Desktop

Update

What’s next