creditkarma-mcp

Credit Karma MCP

Model Context Protocol サーバーです。Claude を Credit Karma に接続し、取引、支出パターン、口座の概要に自然言語でアクセスできるようにします。

警告

AI が開発したプロジェクトです。 このコードベースはすべて Claude Code によって構築され、現在も積極的に保守されています。実装を監査した人間はいません。使用する前に、すべてのコードとツールの権限を確認してください。

できること

Claude に次のようなことを尋ねられます。

• 「最新の取引を同期して」
• 「先月、食費にいくら使った？」
• 「今年、利用額が多い上位の加盟店を見せて」
• 「3月の支出は2月と比べていくら？」
• 「最も利用が多い口座はどれ？」
• 「口座残高を教えて」
• 「取引に対して SQL クエリを実行して」

必要条件

• Claude Desktop または Claude Code
• Node.js 18 以降
• Credit Karma アカウント
• 環境変数を設定しない方法を利用する場合：ContextMint Bridge ブラウザー拡張機能（名称変更された fetchproxy 拡張機能で、同じメンテナーが提供しています。確認方法は以下のオプション A を参照してください）

利用規約の確認

この MCP サーバーを使用することで、以下の内容を確認し、同意したものとみなされます。

1. このサーバーは、お客様ご自身の Credit Karma アカウントにアクセスします。 すべてのリクエストは、ContextMint Bridge 拡張機能を介して、お客様がサインイン済みのブラウザータブから送信されます。ログインしているのはお客様ご自身です。他人のアカウントにアクセスすることはなく、またアクセスできません。

2. このサーバーの利用には、Credit Karma の利用規約が適用されます。 creditkarma.com を直接利用する場合と同様です。ここで特に関連する条項は次のとおりです。

アカウントを他人に販売、譲渡、移転してはなりません。また、他人がお客様になりすまして当社のサービスにログインすることを許可してはなりません。

CK は、ユーザーの指示による第三者のデータ取得を認めています（セクション 3.7）。会員規約にはスクレイピングを明示的に禁止する条項はありませんが、セクション 4.1 では、事前の書面による明示的な同意なしに CK のコンテンツを複製または配布することを制限しています。

このサーバーでツールを実行するたびに、メンテナーが 2026-05-23 に確認したこれらの規約に同意したものとみなされます。特に重要なのは、このサーバーが、お客様に代わってログインする第三者ではなく、お客様ご自身として動作する点です。ツールを操作するのはお客様です。

3. 個人利用に限り、商用利用は禁止です。 このプロジェクトは、Intuit、Credit Karma、またはいかなる金融機関とも提携、推奨、後援、協業関係にありません。これは、Credit Karma のアプリにすでに表示されている取引履歴、支出カテゴリ、アカウント情報を読み取る、個人用の自動化ツールです。他人のアカウントで使用したり、そのコンテンツを再配布したり、他人のために取引や融資の判断を行う目的で使用したりしないでください。

4. このサーバーは動作しなくなる場合があります。 Credit Karma は内部エンドポイントを変更するため、今日動作するものが明日には 404 エラーになる可能性があります。これは非公式な連携の性質です。

5. このサーバーを Credit Karma アカウントに関連して使用した結果については、お客様がすべての責任を負います。 レート制限、アカウントに関する警告、利用停止、または Intuit による措置が含まれます。Credit Karma がお客様の利用に異議を唱えた場合は、このサーバーの使用を中止してください。.env を git にコミットしないでください。CK のセッション／認証情報は認証情報であり、会員規約により、その機密性についてお客様が責任を負います。

このセクションは、メンテナーが誠意をもってまとめた規約の要約です。法的助言ではなく、Credit Karma の実際の会員規約を変更または置き換えるものではありません。

インストール

1. クローンしてビルドする

git clone https://github.com/chrischall/creditkarma-mcp.git
cd creditkarma-mcp
npm install
npm run build

2. 設定する

cp .env.example .env
# See "Authentication" below to get your CK_COOKIES value

3. Claude に追加する

Claude Code — プロジェクトの .mcp.json に追加します。

{
  "mcpServers": {
    "creditkarma": {
      "command": "node",
      "args": ["/absolute/path/to/creditkarma-mcp/dist/index.js"]
    }
  }
}

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json（Mac）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "creditkarma": {
      "command": "node",
      "args": ["/absolute/path/to/creditkarma-mcp/dist/index.js"],
      "env": {
        "CK_COOKIES": "CKTRKID=...; CKAT=eyJ...%3BeyJ...; ..."
      }
    }
  }
}

4. Claude を再起動する

完全に終了してから、もう一度起動します。次に、*「Credit Karma の取引を同期して」*と尋ねます。

認証

Credit Karma では有効期間の短い JWT が使用されます。このサーバーはトークンの自動更新を処理するため、認証情報を設定するのは一度だけです（またはセッションの有効期限が切れたときだけです）。

creditkarma-mcp は優先順位に従って3つの認証方法を試し、最初に成功した方法を使用します。既存の設定は変更なしで引き続き機能します。

1. CK_COOKIES 環境変数（レガシー）。 Claude Desktop の設定または .env に Cookie ヘッダー全体を設定します。上記の設定例で示している方法です。
2. ck_set_session で保存したセッション。 このツールは Cookie ヘッダーを ~/.creditkarma-mcp/session に保存します（モード 0600。CK_SESSION_PATH でパスを上書きできます）。サーバーは起動のたびに保存された値を直接読み込みます（.mcpb バンドルからの場合も同様です）。方法1と2はいずれもローカルで処理され、新しいリフレッシュトークンを持つ方が使用されます。
3. ContextMint Bridge を使ったブラウザーへのフォールバック（環境変数は不要。最も簡単な初期設定です）。 どちらも設定されていない場合、またはローカルセッションの有効期限が切れているか、Credit Karma がそのリフレッシュトークンを拒否した場合に使用されます。サーバーは、ブラウザー拡張機能の ContextMint Bridge を介して、すでにサインイン済みの creditkarma.com タブから CKAT と CKTRKID の Cookie を読み取ります。読み取り後の CK API 呼び出しはすべて Node から直接行われます。拡張機能がリクエストのホットパスに入ることはありません。ContextMint Bridge をインストールし（以下のオプション A を参照）、creditkarma.com にサインインすれば、MCP をそのまま使えます。

CK_DISABLE_FETCHPROXY=1 を設定すると、このフォールバックを無効にできます（認証情報がない場合にエラーになります。ヘッドレス CI で便利です）。

認証情報の取得（環境変数を使う方法）

オプション A — ContextMint Bridge 拡張機能（推奨）

1. リリースページから ContextMint Bridge をインストールします。Chrome の場合は、Chrome 用の zip をダウンロードして解凍し、chrome://extensions でパッケージ化されていない拡張機能を読み込みます（デベロッパー モード → パッケージ化されていない拡張機能を読み込む）。Safari の場合は、現時点では一般向けダウンロードリンクのない ContextMint アプリに同梱されています。今は Chrome またはオプション B を使用してください。

   ContextMint Bridge は、同じメンテナーが新しい名前で提供する fetchproxy ブラウザー拡張機能です。fetchproxy の README の拡張機能からも案内されています。ソースコードは nullnet-app/contextmint-bridge で公開されています。自分でビルドする（npm run build）か、拡張機能を読み込む前に、リリース zip をその隣に公開されている .sha256 ファイルと照合してください。

   shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256
   

2. そのブラウザーで creditkarma.com にサインインします。

3. Claude の設定では CK_COOKIES を設定しないでください。

MCP は最初のツール呼び出し時に chrome.cookies.get を介して HttpOnly の CKAT と CKTRKID の Cookie を読み取り、その後は Node から API に直接アクセスします。再認証する場合（たとえば、Credit Karma からサインアウトされた場合）は、creditkarma.com に再度サインインするだけです。ブラウザーの Bridge が Cookie を読み取れない場合は、MCP がその旨を通知します。Chrome またはオプション B を使用してください。

オプション B — 手動（DevTools）

1. Chrome で creditkarma.com にログインします
2. DevTools を開き、Network → creditkarma.com への任意のリクエストをクリック → Request Headers の順に選択します
3. cookie ヘッダーを右クリックし、Copy value を選択します

その後、Claude の設定または .env の CK_COOKIES に貼り付けるか、Claude 内から Cookie ヘッダーの値を使って ck_set_session を呼び出します。

サーバーはヘッダー内の CKAT Cookie からアクセストークンとリフレッシュ JWT を抽出し、必要に応じてアクセストークンを自動更新します。

セッションの有効期限

• アクセストークン：約15分（透過的に自動更新されます）
• リフレッシュトークン：約8時間
• リフレッシュトークンの有効期限が切れた場合：
  • fetchproxy 経由の場合： creditkarma.com に再度サインインします。MCP は次のツール呼び出し時に新しい Cookie を読み取ります。
  • 環境変数経由の場合： DevTools から新しい Cookie ヘッダーを取得し、CK_COOKIES を更新します（または ck_set_session を呼び出します）。

利用可能なツール

ツール	機能
ck_set_session	ブラウザーの Cookie ヘッダーから認証情報を保存します（CKAT Cookie から JWT を自動抽出します）
ck_forget_session	保存済みセッションファイルを削除し、メモリー内の認証情報を消去します（ローカルのみ。同期済みの取引は保持されます）
ck_sync_transactions	取引をローカルの SQLite データベースに同期し、アカウント残高を更新します
ck_get_account_balances	すべてのアカウントの残高を表示します。金融機関、種類、下 4 桁、現在の残高、利用可能なクレジットと利用限度額（カードの場合）、基準時刻、stale フラグが含まれます。refresh: true を指定すると、最初に最新の情報を取得します。include_matched: true を指定すると、リンク済みアカウントと重複する信用情報の行も表示します
ck_list_transactions	フィルター（日付、アカウント、カテゴリー、加盟店、金額）を指定して取引を一覧表示します
ck_get_recent_transactions	直近の N 件の取引を取得します
ck_get_spending_by_category	カテゴリー別の支出合計を表示します
ck_get_spending_by_merchant	加盟店別の支出合計を表示します
ck_get_account_summary	アカウント別の取引件数と合計を表示します
ck_query_sql	ローカルデータベースに対して読み取り専用の SQL クエリを実行します（最大 max_rows 件を返します。デフォルトは 500、最大は 5000 件で、該当する行がそれより多い場合は truncated: true を返します）

仕組み

Credit Karma の GraphQL API から取引を取得し、ローカルの SQLite データベース（デフォルト：~/.creditkarma-mcp/transactions.db）に同期します。すべてのクエリツールはこのローカルデータベースを参照するため、高速で、オフラインでも利用でき、SQL でクエリできます。

同期方法：デフォルトでは差分同期を行います（前回の同期日以降を取得し、更新に備えて 30 日分さかのぼります）。日付の制限なしに全履歴を取得するには force_full: true を指定します。最初から処理を開始しますが、max_pages に達して中断したバックフィルは、force_full を繰り返すと続きから再開します。同期に失敗した場合、またはカーソルが停止して同期が中断した場合、force_full は 1 ページ目から再開します（通常の呼び出しでは保存済みのカーソルから再試行します）。

アカウント残高：各同期では、2 つのソースから残高も 1 回更新します（どちらか一方で失敗した場合も、その失敗は結果の balances に報告され、例外は発生しません。取引の同期は引き続き行われます）。

• リンク済みアカウント — クレジットカードやローンを含むすべての種類のアカウント — は、Credit Karma の Manage accounts ページの背後にあるアカウント集約サービス（Credit Karma が発行するトークンを使ってアクセスする、Intuit のアカウント保管庫）から取得します。各アカウントはアカウント ID を使って取引アカウントと照合され、基準時刻には各アカウント自身の最終更新時刻が使われます。カードの行には利用限度額が含まれます。利用可能なクレジットは、利用限度額から残高を差し引いて計算されます。
• クレジットカードとローン は、信用情報機関の信用情報からも取得します（デフォルトは TransUnion です。切り替えるには CK_CREDIT_BUREAU=equifax を設定します）。基準時刻は信用情報の最終報告時点で、通常は 2～5 週間前です。利用限度額は含まれますが、下 4 桁は含まれません。解約済みのアカウントは除外されます。信用情報上のアカウントがリンク済みアカウントと明らかに同一の場合（貸し手が同じ、利用限度額が同じ、残高が近い、リンク済みアカウントの残高のほうが新しい、かつほかに一致するアカウントがない場合）は、重複として非表示になります。表示するには include_matched: true を指定してください。確証が持てない組み合わせが非表示になることはありません。

残高には取引と同じ符号規則が適用されます。資産は正の値、返済義務のある金額（カード残高、ローン）は負の値です。credit_limit と available_balance は正の値です。リンク済みアカウントでは balance_as_of が 7 日より古い場合、信用情報機関の情報では 35 日より古い場合に、stale は true になります。

自動更新：アクセストークンの有効期限が切れている場合、サーバーは同期の前に自動で更新します。リフレッシュトークンも期限切れの場合は、再認証を求めるエラーが発生します。

データベーススキーマ

transactions (id, date, description, status, amount, account_id, category_id, merchant_id, raw_json)
accounts     (id, name, type, provider_name, display, last4, account_urn,
              current_balance, available_balance, credit_limit,
              balance_as_of, balances_synced_at, balance_source, matched_account_id)
account_aliases (alias, account_id)
categories   (id, name, type)
merchants    (id, name)
sync_state   (key, value)

設定

環境変数	説明	デフォルト
CK_COOKIES	サインイン済みの creditkarma.com リクエストから取得した完全な Cookie ヘッダー	(未設定 — fetchproxy にフォールバックします)
CK_DISABLE_FETCHPROXY	1 に設定すると、fetchproxy へのフォールバックをスキップします（ヘッドレス／CI）	(未設定)
CK_DB_PATH	SQLite データベースファイルへのパス	~/.creditkarma-mcp/transactions.db
CK_CREDIT_BUREAU	カードとローンの残高に使用する信用情報機関のレポート：transunion または equifax	transunion
CK_DEBUG	1 に設定すると、認証情報の取得元、Cookie 名、JWT のタイミング、トークン更新リクエスト／レスポンスを stderr に記録します。トークンや Cookie の値は記録されません	(未設定)

トラブルシューティング

「CK auth: set CK_COOKIES, or call the ck_set_session MCP tool, or install the ContextMint Bridge extension…」 — どちらの認証方法も設定されていません。Claude の設定で CK_COOKIES を指定するか、ContextMint Bridge をインストールして、ブラウザーで creditkarma.com にサインインしてください。

「TOKEN_EXPIRED」 — リフレッシュトークンの有効期限が切れています。creditkarma.com に再度サインインする（ContextMint Bridge の方法）か、DevTools から新しい Cookie ヘッダーを取得して CK_COOKIES を更新するか、ck_set_session を呼び出してください。

新たにサインインしたのに ck_healthcheck が失敗する — steps／failed_step を確認してください。認証情報の検索、トークンの有効性、更新、プローブの各結果が個別に報告されます。refresh の失敗が CDN/WAF（Akamai）によるブロック と報告された場合、リクエストは Credit Karma に到達していないため、サインインし直しても解決しません。更新時に session rejected と報告された場合、トークンが新しく見えても Credit Karma がセッションを終了しています。アイドル状態のタブはサインアウトされます。再度サインインしてください。直前にサインインしたにもかかわらず同じ理由で失敗する場合は、CK_DEBUG=1 を設定して再起動し、docs/refresh-ground-truth.md と照合してください。

「fetchproxy fallback failed」 — 環境変数の方法が設定されておらず、拡張機能にも接続できませんでした。ContextMint Bridge がインストールされていること、Credit Karma にサインインしていること、拡張機能が実行中であること（拡張機能のポップアップを開いて確認してください）を確認してください。フォールバックを無効にするには、CK_DISABLE_FETCHPROXY=1 を設定してください。

同期でトランザクションが 0 件返される — 認証情報が最新か確認してください。CKAT Cookie 内のリフレッシュトークンは約 8 時間で期限切れになります。

ツールが表示されない — Claude Desktop を完全に終了してから再起動してください。Claude Code では /mcp を実行してサーバーの状態を確認してください。

「No such file or directory: dist/bundle.js」 — npm run build を実行してください（tsc だけでは不十分です）。

セキュリティ

• 認証情報は、保存済みセッションファイル（~/.creditkarma-mcp/session または CK_SESSION_PATH）、Claude の設定／.env、またはブラウザーの Cookie jar（ContextMint Bridge の方法）にのみ保存されます
• 保存済みセッションファイルは、ck_set_session およびトークン更新のたびに、0700 のディレクトリ内にモード 0600（所有者のみ読み書き可能）で書き込まれます
• ck_set_session は、JWT の exp がすでに過去の時刻になっているリフレッシュトークンの保存を拒否し、古い認証情報によって保存済みセッションが汚染されるのを防ぎます
• fetchproxy の方法では、ユーザーのブラウザーから chrome.cookies.get を使って Cookie を直接読み取りますが、メモリ内だけにとどまりません。トークンが更新されるたびにセッションがローテーションされ、ローテーション後の CKAT／CKTRKID Cookie ヘッダーは、0700 のディレクトリ内にモード 0600 で保存済みセッションファイル（~/.creditkarma-mcp/session または CK_SESSION_PATH）へ保存されます。これには fetchproxy のみを使うユーザーも含まれるため、再起動後にブラウザーを再読み込みせずに復旧できます。削除するには ck_forget_session を呼び出すか、ファイルを削除してください
• サーバーは認証情報を記録しません（CK_DEBUG=1 の場合も、名前、タイミング、秘匿化された本文のみを記録します）。警告は stderr にのみ出力されます（stdout は MCP JSON-RPC ストリーム専用です）
• ck_query_sql では SELECT クエリのみが許可され、Credit Karma への書き込みはできません。クエリは読み取り専用の接続で実行され、node:sqlite の prepare() は複数文の入力のうち最初の文のみをコンパイルします。最初の ; 以降はすべて黙って無視され、実行されません

アンインストール／リセット

サーバーはディスク上に2種類のデータを保持します。拡張機能をアンインストールしたり、使用を停止したりしても、どちらも削除されません。

内容	デフォルトのパス	削除方法
保存されたセッション — creditkarma.com の Cookie ヘッダー全体（有効なアクセス・トークンとリフレッシュ・トークン）	~/.creditkarma-mcp/session (CK_SESSION_PATH)	ck_forget_session を呼び出すか、ファイルを削除します
同期された取引履歴（口座、加盟店、金額、説明）	~/.creditkarma-mcp/transactions.db (CK_DB_PATH) と、関連する -wal ／ -shm ファイル	サーバーを終了してから、ファイル（または ~/.creditkarma-mcp/ ディレクトリ全体）を削除します

ck_forget_session はローカルでのみ動作します。Credit Karma には接続しないため、トークン自体を無効にするには creditkarma.com からサインアウトしてください。Claude の設定で CK_COOKIES が設定されている場合は、そこからも削除してください。また、ContextMint Bridge がインストールされている場合は、ブラウザーで creditkarma.com からサインアウトしてください。そうしないと、次回の呼び出しでセッションが再び取得されます。

開発

npm test               # run the test suite (vitest)
npm run build          # compile TypeScript → dist/, bundle for MCPB
npm run test:watch     # watch mode
npm run test:coverage  # coverage report (CI enforces 100% on src/**)

バージョンは Tag & Bump GitHub Action (.github/workflows/tag-and-bump.yml) によって自動的に更新されます。手動で更新しないでください。

プルリクエスト

個人での作業も含め、変更はプルリクエスト経由で取り込みます。リリースノートはマージ済みのプルリクエストのみから生成されます（設定は .github/release.yml）。すべてのプルリクエストに、次のラベルのいずれかを付けてください：enhancement、bug、security、refactor、documentation、test、dependencies、ci、または ignore-for-release（リリースノートから除外）。プルリクエストのタイトルは変更履歴の箇条書きになるため、ユーザー向けの項目として記述してください。

プロジェクト構成

src/
  auth.ts               resolveAuth() — three-path priority (CK_COOKIES env / ck_set_session cache / fetchproxy), plus loadAuthIntoClient()
  client.ts             Credit Karma GraphQL client (auto-refresh, JWT helpers, cookie parser, balance operations)
  index.ts              MCP server entry point; bootstraps tokens from the saved session / CK_COOKIES
  db.ts                 SQLite schema, migrations, and upsert helpers
  vault.ts              Linked-account balances from Intuit's account vault
  creditReport.ts       Credit-report balances (cards and loans, weeks old)
  matching.ts           Pairs credit-report accounts with the linked accounts they duplicate
  json.ts               Small helpers for reading untyped API JSON
  transaction.graphql   Documents the transaction fields we read (sent as a persisted-query hash, not this text)
  tools/
    auth.ts             ck_set_session — refuses stale refresh tokens, saves ~/.creditkarma-mcp/session at 0600;
                        ck_forget_session — deletes it and clears in-memory credentials
    sync.ts             ck_sync_transactions — incremental sync with resume-on-failure
    query.ts            ck_list_transactions, ck_get_recent_transactions,
                        ck_get_spending_by_category, ck_get_spending_by_merchant,
                        ck_get_account_summary
    balances.ts         ck_get_account_balances + the balance refresh run by every sync
    sql.ts              ck_query_sql — SELECT-only escape hatch
tests/
  helpers.ts            Shared test helpers (fakeServer, makeJwt)
  auth.test.ts          resolveAuth + loadAuthIntoClient (mocks @fetchproxy/bootstrap)
  client.test.ts
  db.test.ts
  tools/
    auth.test.ts
    sync.test.ts
    query.test.ts
    sql.test.ts

ライセンス

MIT