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 会按优先级尝试三种认证方式；最先成功的方式将被采用。现有配置无需更改，仍可继续使用。

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 压缩包并解压，然后在 chrome://extensions 中以解压缩方式加载（开发者模式 → 加载已解压的扩展程序）。Safari：它包含在 ContextMint 应用中，目前尚无公开下载链接——请暂时使用 Chrome 或选项 B。

   ContextMint Bridge 是浏览器扩展 fetchproxy 的新名称，维护者未变——fetchproxy 自身的 README（扩展）也指向它。其源代码公开于 nullnet-app/contextmint-bridge：你可以自行构建（npm run build），也可以在加载发布压缩包前，将其与旁边发布的 .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 中调用 ck_set_session 并提供 Cookie 标头的值。

服务器会从标头中的 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 可遍历全部历史记录，不设日期截止范围——从最早记录开始；但如果上一次 force_full 因达到 max_pages 而暂停，再次运行时会继续回填。同步失败或因游标卡住而停止后，force_full 会从第 1 页重新开始（普通调用则从保存的游标处重试）。

账户余额：每次同步也会从两个来源刷新一次余额（任一来源失败时，错误会报告在结果的 balances 中，不会抛出异常；交易记录仍会继续同步）：

• 关联账户——包括所有类型的账户，包括信用卡和贷款——来自 Credit Karma 的管理账户页面背后的账户聚合器（Intuit 的账户保险库，通过 Credit Karma 签发的令牌访问）。每个账户会根据其账户 ID 与交易记录中的账户匹配；该账户的数据截至时间为其自身上次刷新的时间。银行卡记录包含信用额度；可用信用额度按信用额度减去余额计算。
• 信用卡和贷款也来自你的信用报告（默认使用 TransUnion；设置 CK_CREDIT_BUREAU=equifax 可切换）。数据截至征信机构的上次报告时间，通常为 2–5 周前；包含信用额度，但不包含末 4 位。已关闭的账户会被剔除。如果某条信用报告账户记录明显与某个关联账户相同（贷方相同、信用额度相同、余额相近、关联账户的余额时间更新——且没有其他账户符合），则会将其作为重复项隐藏；传入 include_matched: true 可查看。无法确定的配对不会隐藏。

余额遵循交易记录的正负号规则：资产为正，欠款（银行卡余额、贷款）为负；credit_limit 和 available_balance 为正。当关联账户的 balance_as_of 超过 7 天，或信用报告账户的 balance_as_of 超过 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 可将身份验证跟踪信息输出到 stderr — 凭据来源、Cookie 名称、JWT 时间信息以及令牌刷新请求/响应。绝不记录令牌或 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，重新登录也无济于事。若 refresh 提示 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 存储区（ContextMint Bridge 方式）中
• ck_set_session 和每次令牌刷新轮换都会将已保存的会话文件权限设为 0600（仅所有者可读写），并存放在权限为 0700 的目录中
• ck_set_session 拒绝保存 JWT exp 已过期的刷新令牌，避免过期凭据污染已保存的会话
• fetchproxy 方式通过 chrome.cookies.get 直接从用户的浏览器读取 Cookie，但并非仅存于内存：每次令牌刷新都会轮换会话，并将轮换后的 CKAT/CKTRKID Cookie 标头以 0600 权限保存在已保存的会话文件（~/.creditkarma-mcp/session 或 CK_SESSION_PATH）中，文件所在目录权限为 0700 — 也包括仅使用 fetchproxy 的用户 — 因此重启后无需重新读取浏览器即可恢复会话。调用 ck_forget_session（或删除该文件）即可将其移除
• 服务绝不记录凭据（包括在 CK_DEBUG=1 时，也只会记录名称、时间信息和已脱敏的正文）；警告仅输出到 stderr（stdout 专用于 MCP JSON-RPC 流）
• ck_query_sql 仅允许执行 SELECT 查询 — 不会向 Credit Karma 写入数据。查询通过只读连接运行，而 node:sqlite 的 prepare() 只会编译多语句输入中的第一条语句：第一个 ; 之后的所有内容都会被静默忽略，绝不会执行

卸载 / 重置

服务会在磁盘上保留两项数据。卸载扩展或停止使用后，它们都不会被删除：

内容	默认路径	删除方式
已保存的会话 — 完整的 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）自动递增。请勿手动递增。

拉取请求

所有更改都通过 PR 合并，即使是独立开发也不例外——发布说明仅根据已合并的 PR 生成（配置位于 .github/release.yml）。为每个 PR 添加以下标签之一：enhancement、bug、security、refactor、documentation、test、dependencies、ci 或 ignore-for-release（不纳入说明）。PR 标题会成为变更日志中的条目，请将其写成面向用户的描述。

项目结构

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