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