karbon-mcp-server

Karbon MCP Server

🚧 早期リリース — このプロジェクトは始まったばかりで、今後数日間、積極的に更新を続けます。内容は急速に変わる可能性があります。安定性が必要な場合はバージョンを固定し、また近いうちにご確認ください。

Model Context Protocol に対応する Karbon の非公式プラクティスマネジメントサーバーです。Claude Code、Claude Desktop、GitHub Copilot、または MCP 対応クライアントを Karbon インスタンスに接続し、自然言語を使って連絡先、作業項目、時間、請求書、支払い、ファイルなどを操作できます。

免責事項： これはコミュニティプロジェクトであり、Karbon とは提携関係になく、承認も受けていません。自己責任でご利用ください。

機能

領域	ツール
連絡先	list_contacts, get_contact, create_contact, update_contact
組織	list_organizations, get_organization, create_organization, update_organization
クライアントグループ	list_client_groups, get_client_group, create_client_group, update_client_group
作業項目	list_work_items, get_work_item, get_estimate_summary, create_work_item, update_work_item
メモとコメント	get_note, create_note, get_comment
タイムシート	list_timesheets, get_timesheet, list_time_entries, get_time_entry（読み取り専用）
請求書	list_invoices, get_invoice（読み取り専用）
支払い	list_payments, get_payment。さらに、KARBON_ALLOW_PAYMENT_WRITES=true の設定時に create_manual_payment, delete_manual_payment, reverse_manual_payment を利用できます
名刺	get_business_card, update_business_card — 連絡先情報（メール、電話番号、住所）
カスタムフィールド	list_custom_fields, get_custom_field_values, set_custom_field_values, create_custom_field, delete_custom_field
ファイル	list_entity_files, download_file, upload_file
チーム	list_teams, get_team, add_team_members, remove_team_member
作業スケジュール	get_work_schedule, create_work_schedule, update_work_schedule
ユーザー	list_users, get_user
アカウント	get_tenant_settings, list_work_templates, get_work_template

get_contact、get_organization、get_client_group では、Karbon キーの代わりに独自の UserDefinedIdentifier を使ってレコードを検索することもできます。税務ソフトウェアから ID を同期している場合に便利です。

すべての一覧表示ツールは OData のフィルタリング（$filter）、並べ替え（$orderby）、ページネーション（$top／$skip）に対応しています。そのため、「今月が期限の進行中の作業項目を表示して」のような依頼を、AI が正確なクエリとして表現できます。

前提条件

• Node.js 18+
• Karbon API の認証情報。Karbon で Settings → Connected Apps → API Applications に移動し、Bearer Token と Access Key をコピーしてください。(Karbon のヘルプ記事)

セットアップ

Claude Desktop、claude.ai/Cowork、ChatGPT の手順を追ったガイド（開発者以外の方向け）は docs/client-guides.md にあります。

Claude Desktop：ワンクリックバンドル

最新リリースから karbon-mcp-server.mcpb をダウンロードし、ダブルクリックします。Claude Desktop に Karbon の 2 つのキーを入力するフォームが表示されます（キーは OS によって安全に保管されます）。読み取り専用の切り替えもできます。ターミナルは不要です。手順ガイド。

1 行でインストール（事前のダウンロード不要）

Node.js がない場合でも、これらのコマンドは Node.js の有無を確認し（可能な場合は winget/Homebrew でインストール）、npm からセットアップウィザードを直接実行します。リポジトリのクローンも、手動でのダウンロードも不要です。

# 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

Node.js がインストール済みなら最速：自動セットアップ

npx -y karbon-mcp-server setup

セットアップでは、いくつかの簡単な質問が表示されます。プロジェクト単位またはユーザー単位のインストール、API キー（スキップ可能）、読み取り専用モードを有効にするかどうかを選択すると、残りはすべて自動で行われます。

• このプロジェクト（デフォルト）：.mcp.json（Claude Code）に加え、プロジェクト内にフォルダーがあれば .vscode/mcp.json と .cursor/mcp.json を書き込みます。
• ユーザーアカウント：お使いのマシンにインストールされている MCP クライアント（Claude Code、Codex、Claude Desktop、VS Code、Cursor）を検出し、それぞれにサーバーを追加します（Claude Code と Codex では、各自の mcp add CLI を使用します）。

続いて、Karbon の 2 つのキーを入力するよう求められます（どちらも Enter キーでスキップできます）。

• 入力内容はマスク表示されます。各文字は * で表示され、その後、先頭 4 文字と末尾 4 文字のプレビュー（1a2b****5c6d のような形式で、Karbon のサイトと同じ形式）が表示されます。これにより入力内容を確認でき、形式が正しくないように見える場合は控えめな警告が表示されます（Bearer Token は GUID、Access Key は ey... で始まります）。
• キーはお使いのマシン上にあるMCP クライアントのローカル設定ファイルにのみ書き込まれます。これは手動セットアップで使用するファイルと同じです。キーがほかの場所に送信されることはありません。
• スキップした場合はプレースホルダー値が書き込まれ、後で編集する必要があるファイルが正確に通知されます。

既存の設定ファイルは変更前にすべてバックアップされ、上書きではなくマージされます。また、実際の認証情報がプレースホルダーに置き換えられることはありません（セットアップを再実行してキーの入力をスキップしても、既存のキーは保持されます）。プロジェクト単位でインストールする場合は、設定ファイルを gitignore に追加してください。キーは設定ファイルにプレーンテキストで保存されます。

オプション：

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

ワンクリックインストール

上記の VS Code / Cursor にインストールバッジを使うと、プレースホルダーの認証情報を使ったサーバーエントリーが作成されます。インストール後、YOUR_BEARER_TOKEN と YOUR_ACCESS_KEY を実際のキーに置き換えてください。VS Code ではコマンドパレットから MCP: Open User Configuration を選択し、Cursor では ~/.cursor/mcp.json を編集します。

プレースホルダーを置き換える前にサーバーを実行しても、問題なく起動し、どのツールも不可解なエラーを返すことなくセットアップ手順を表示します。そのため、AI アシスタントに「Karbon が動作しないのはなぜ？」と尋ねて、必要な手順を教えてもらうこともできます。

手動で設定したい場合は、以下に各クライアントの手順があります。

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

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）

ワークスペースの .vscode/mcp.json（またはユーザー用の 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

~/.cursor/mcp.json に追加します（または上記のインストールバッジを使用します）。

{
  "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

または ~/.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 のチャット、Claude Cowork（リモートコネクター）

これらのクライアントはローカルサーバーを起動できず、HTTPS 経由でリモート MCP サーバーに接続するだけです。このパッケージには、その用途にぴったりのストリーミング可能な HTTP モードが含まれているため、事務所はセルフホストして、Karbon のキーを自社のインフラストラクチャ内に保持できます。

KARBON_BEARER_TOKEN=... KARBON_ACCESS_KEY=... KARBON_HTTP_SECRET=some-long-random-string \
  npx -y karbon-mcp-server --http --port 8787

MCP エンドポイント /mcp/<your-secret>（および /health チェック）が提供されます。お好きな方法で HTTPS 経由で公開してください。手軽で無料の方法としては、Cloudflare Tunnel があります。

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

次に、URL（例：https://your-tunnel.trycloudflare.com/mcp/your-secret）を以下のように追加します。

• claude.ai / Cowork：設定 → コネクター → カスタムコネクターを追加（Pro／Max／Team／Enterprise プラン）
• ChatGPT：設定 → コネクター（すべてのツールにアクセスするには開発者モードが必要です）

**セキュリティに関する注意：**完全な URL を知っている人は誰でも、API キーと同じ Karbon へのアクセス権を持つため、長くランダムな KARBON_HTTP_SECRET を使用し、必ず HTTPS を経由させ、リモート利用では KARBON_READ_ONLY=true の設定を検討してください。このサーバーには、共有またはホスト型のインスタンスは意図的に用意されていません。キーは、必ずご自身が管理するインフラストラクチャ内にのみ保存してください。

設定

環境変数	必須	説明
KARBON_BEARER_TOKEN	はい	Karbon Connected Apps の Bearer トークン
KARBON_ACCESS_KEY	はい	Karbon Connected Apps のアクセスキー（JWT）
KARBON_READ_ONLY	いいえ	すべての作成／更新ツールを無効にするには、true を設定します
KARBON_ALLOW_PAYMENT_WRITES	いいえ	支払い書き込みツール（手動支払いの作成／削除／取り消し）を有効にするには、true を設定します。デフォルトでは無効です
KARBON_API_BASE_URL	いいえ	API のベース URL を上書きします（デフォルトは https://api.karbonhq.com/v3）
KARBON_HTTP_SECRET	いいえ	HTTP モードのみ：エンドポイントのシークレットパスセグメント（/mcp/<secret>）
PORT	いいえ	HTTP モードのみ：待ち受けポート（デフォルトは 8787。--port が優先されます）

読み取り専用モード

AI に Karbon のデータを絶対に変更させたくない場合は、KARBON_READ_ONLY=true を設定するか、--read-only を渡してください。このモードでは書き込みツールは一切登録されないため、AI からは見えません。download_file も無効になります。Karbon 自体は変更しませんが、ローカルディスクに書き込むため、読み取り専用ではあらゆる場所への書き込みを禁止します。セットアップウィザードでこの設定を指定できます。

**後から変更する場合：**セットアップでは常に切り替え設定（"KARBON_READ_ONLY": "true" または "false"）が明示的に書き込まれるため、設定ファイルですぐに確認できます。値を変更してクライアントを再起動してください。これに応じて書き込みツールが表示または非表示になります（読み取り専用モードではツールが一切登録されないため、AI からは見えません）。または、セットアップを再実行してキーの入力を省略（Enter キーを押す）してください。保存済みのキーは保持され、新しい読み取り専用の設定が適用されます。注意点として、claude／codex CLI が管理する項目は、セットアップを再実行しても変更されません。その場合は、先に claude mcp remove karbon（または codex mcp remove karbon）を実行してから、セットアップを再実行してください。

支払いの書き込み（追加のオプトイン）

支払いの記録、削除、取り消しは財務記録に影響するため、この 3 つのツールには個別のスイッチが設けられています。他の書き込みが有効でも、KARBON_ALLOW_PAYMENT_WRITES=true を設定するか、--allow-payment-writes を渡すまでは登録されません。セットアップでは、設定ファイルですぐに見つけて変更できるよう、切り替え設定に "false" が書き込まれます。セットアップを再実行しても、手動で変更した値がリセットされることはありません。読み取り専用モードが常に優先されるため、KARBON_READ_ONLY=true の場合、支払いの書き込みは引き続き無効です。

認証情報に関する注意

セットアップウィザードにキーを入力する場合も、設定ファイルに手動で貼り付ける場合も、保存先は必ず1か所です。ご利用のMCPクライアントのローカル設定ファイルであり、すべて手動でセットアップした場合と同じファイルです。このプロジェクトがキーをほかの場所に送信することはありません。すべてのstdio MCP サーバーと同様に、キーはそのファイルにプレーンテキストで保存されるため、パスワードと同じように扱ってください。キーと同じように、Karbon アカウントへのアクセス権を与えるものです。キーが漏えいした場合は、Karbon の「Settings」→「Connected Apps」で再発行してください。

プロンプトの例

• 「Jane Smith の連絡先レコードを見つけて、名刺の詳細を表示してください。」
• 「Jane Smith のメールアドレスと電話番号を更新してください。」
• 「自分に割り当てられた進行中の作業項目を、期限順に一覧表示してください。」
• 「Hendersons の税務申告は予算を超過していますか？」
• 「支払い待ちの請求書と、それぞれの金額を教えてください。」
• 「Acme Corp の2025年の税務申告について、担当者を [email protected]、開始日を来週月曜日として作業項目を作成してください。」
• 「Smith の作業項目に、今日のクライアントとの通話内容をまとめたメモを追加してください。」
• 「先週、クライアントの作業に何時間記録されましたか？」
• 「Miller のオンボーディング作業項目には、どのファイルが添付されていますか？」

開発

git clone https://github.com/Mad-Man-Dan/karbon-mcp-server.git
cd karbon-mcp-server
npm install
npm test        # builds, then runs the smoke tests (tool matrix across flag combos)

リリースは自動化されています。v* タグをプッシュすると CI が実行され、信頼されたパブリッシング（OIDC — トークン不要）を通じて npm に公開され、MCP Registry の掲載情報が更新されます。

M CP Inspector を使ってローカルでテストできます。

npx @modelcontextprotocol/inspector \
  -e KARBON_BEARER_TOKEN=... -e KARBON_ACCESS_KEY=... \
  node dist/index.js

Karbon API のドキュメントは developers.karbonhq.com で公開されており、OpenAPI 仕様は karbonhq/karbon-api-reference にあります。

貢献

貢献を歓迎します。Issue または PR を作成してください。

ライセンス

MIT