Karbon MCP Server

Karbon MCP Server

🚧 Early release — this project is brand new and we're actively making updates over the next few days. Things may change quickly; pin a version if you need stability, and check back soon.

An unofficial Model Context Protocol server for Karbon practice management. Connect Claude Code, Claude Desktop, GitHub Copilot, or any MCP-compatible client to your Karbon instance and work with contacts, work items, time, invoices, payments, files, and more using natural language.

Disclaimer: This is a community project and is not affiliated with or endorsed by Karbon. Use at your own risk.

Features

get_contact, get_organization, and get_client_group can also look records up by your own UserDefinedIdentifier instead of the Karbon key — handy if you sync IDs from your tax software.

All list tools support OData filtering ($filter), ordering ($orderby), and pagination ($top/$skip) — so you can ask things like *"show my in-progress work items due this month"* and the AI can express that as a precise query.

Prerequisites

• Node.js 18+
• Karbon API credentials. In Karbon go to Settings → Connected Apps → API Applications and copy your Bearer Token and Access Key. (Karbon help article)

Setup

Step-by-step walkthroughs for Claude Desktop, claude.ai/Cowork, and ChatGPT (written for non-developers) are in docs/client-guides.md.

Claude Desktop: one-click bundle

Download karbon-mcp-server.mcpb from the latest release and double-click it. Claude Desktop opens a form for your two Karbon keys (stored securely by your OS) plus a read-only toggle — no terminal needed. Walkthrough.

One-line install (nothing to download first)

No Node.js? These check for it (installing via winget/Homebrew where possible), then run the setup wizard straight from npm — no repo clone, no manual download:

# Windows (PowerShell)

irm https://raw.githubusercontent.com/Mad-Man-Dan/karbon-mcp-server/main/scripts/install.ps1 | iex

# macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Mad-Man-Dan/karbon-mcp-server/main/scripts/install.sh | bash

Quickest with Node.js installed: automatic setup

npx -y karbon-mcp-server setup

Setup asks a few quick questions — project or user-level install, your API keys (skippable), and whether to enable read-only mode — then does everything else automatically:

• This project (the default): writes .mcp.json (Claude Code), plus .vscode/mcp.json and .cursor/mcp.json if those folders exist in the project.
• User account: detects which MCP clients are installed on your machine — Claude Code, Codex, Claude Desktop, VS Code, Cursor — and adds the server to each (for Claude Code and Codex it uses their own mcp add CLI).

It then offers to take your two Karbon keys (Enter skips either one):

• Input is masked — you see a * per character, then a first-4/last-4 preview (like 1a2b****5c6d, the same style Karbon's site uses) so you can confirm what was entered, with a gentle warning if the format looks off (the Bearer Token is a GUID; the Access Key starts with ey...).
• Keys are written only to your MCP client's local config file on your machine — the same file a manual setup would use. They are never sent anywhere else.
• If you skip, placeholder values are written and setup tells you exactly which file(s) to edit later.

It backs up every existing config file before touching it, merges rather than overwrites, and never replaces real credentials with placeholders (re-running and skipping the prompts keeps your existing keys). If you go project-level, gitignore the config files — your keys live in them in plain text.

Options:

npx -y karbon-mcp-server setup --scope project          # skip the question

npx -y karbon-mcp-server setup --scope user npx -y karbon-mcp-server setup --read-only # disable all write tools npx -y karbon-mcp-server setup --client vscode,cursor # only these clients

ids: claude-code, codex, claude-desktop, vscode, cursor

npx -y karbon-mcp-server setup --print # just print the JSON

One-click installs

The Install in VS Code / Cursor badges above create the server entry for you with placeholder credentials. After installing, replace YOUR_BEARER_TOKEN and YOUR_ACCESS_KEY with your real keys — in VS Code via the Command Palette → MCP: Open User Configuration, in Cursor by editing ~/.cursor/mcp.json.

If you run the server before replacing the placeholders, it starts fine and every tool responds with setup instructions instead of failing cryptically — so you can even ask your AI assistant "why isn't Karbon working?" and it will tell you what to do.

Prefer to configure things by hand? Each client is below.

Claude Code

claude mcp add karbon \

--env KARBON_BEARER_TOKEN=your-bearer-token \ --env KARBON_ACCESS_KEY=your-access-key \ -- npx -y karbon-mcp-server

Claude Desktop

Add to claude_desktop_config.json:

{

"mcpServers": { "karbon": { "command": "npx", "args": ["-y", "karbon-mcp-server"], "env": { "KARBON_BEARER_TOKEN": "your-bearer-token", "KARBON_ACCESS_KEY": "your-access-key" } } } }

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your workspace (or your user mcp.json):

{

"servers": { "karbon": { "command": "npx", "args": ["-y", "karbon-mcp-server"], "env": { "KARBON_BEARER_TOKEN": "your-bearer-token", "KARBON_ACCESS_KEY": "your-access-key" } } } }

Cursor

Add to ~/.cursor/mcp.json (or use the install badge above):

{

"mcpServers": { "karbon": { "command": "npx", "args": ["-y", "karbon-mcp-server"], "env": { "KARBON_BEARER_TOKEN": "your-bearer-token", "KARBON_ACCESS_KEY": "your-access-key" } } } }

Codex (OpenAI Codex CLI)

codex mcp add karbon \

--env KARBON_BEARER_TOKEN=your-bearer-token \ --env KARBON_ACCESS_KEY=your-access-key \ -- npx -y karbon-mcp-server

Or add to ~/.codex/config.toml:

[mcp_servers.karbon]

command = "npx" args = ["-y", "karbon-mcp-server"]

[mcp_servers.karbon.env] KARBON_BEARER_TOKEN = "your-bearer-token" KARBON_ACCESS_KEY = "your-access-key"

ChatGPT, claude.ai chat & Claude Cowork (remote connectors)

These clients can't launch local servers — they only connect to a remote MCP server over HTTPS. This package includes a streamable-HTTP mode for exactly that, so a firm can self-host it and keep their Karbon keys in their own infrastructure:

KARBON_BEARER_TOKEN=... KARBON_ACCESS_KEY=... KARBON_HTTP_SECRET=some-long-random-string \

npx -y karbon-mcp-server --http --port 8787

This serves the MCP endpoint at /mcp/ (plus a /health check). Expose it over HTTPS however you like — the quickest free option is a Cloudflare Tunnel:

cloudflared tunnel --url http://localhost:8787

Then add the URL (e.g. https://your-tunnel.trycloudflare.com/mcp/your-secret) as:

• claude.ai / Cowork: Settings → Connectors → Add custom connector (Pro/Max/Team/Enterprise plans)
• ChatGPT: Settings → Connectors (requires developer mode for full tool access)

Security notes: anyone with the full URL has the same Karbon access as your API keys, so use a long random KARBON_HTTP_SECRET, always front it with HTTPS, and consider KARBON_READ_ONLY=true for remote use. There is deliberately no shared/hosted instance of this server — your keys should only ever live on infrastructure you control.

Configuration

Read-only mode

If you want a guarantee that the AI can never modify your Karbon data, set KARBON_READ_ONLY=true (or pass --read-only). Write tools are not registered at all in this mode, so the AI never sees them. This also disables download_file — it doesn't change Karbon, but it writes to the local disk, and read-only means no writes anywhere. The setup wizard asks about this.

Changing it later: setup always writes the toggle explicitly ("KARBON_READ_ONLY": "true" or "false"), so the switch is right there i