creditkarma-mcp 2.0.1 → 2.0.3

package/README.md

@@ -3,7 +3,7 @@
 A [Model Context Protocol](https://modelcontextprotocol.io) server that connects Claude to [Credit Karma](https://www.creditkarma.com), giving you natural-language access to your transactions, spending patterns, and account summaries.
 
 > [!WARNING]
-> **AI-developed project.** This codebase was entirely built and is actively maintained by [Claude Sonnet 4.6](https://www.anthropic.com/claude). No human has audited the implementation. Review all code and tool permissions before use.
+> **AI-developed project.** This codebase was entirely built and is actively maintained by [Claude Code](https://www.anthropic.com/claude). No human has audited the implementation. Review all code and tool permissions before use.
 
 ## What you can do
 
@@ -21,6 +21,7 @@ Ask Claude things like:
 - [Claude Desktop](https://claude.ai/download) or [Claude Code](https://claude.ai/code)
 - [Node.js](https://nodejs.org) 18 or later
 - A Credit Karma account
+- [Google Chrome](https://www.google.com/chrome/) — used once for the scripted auth flow (optional; you can copy the cookie manually instead)
 
 ## Installation
 
@@ -81,21 +82,33 @@ Credit Karma uses short-lived JWTs. This server handles automatic token refresh
 
 ### Getting your credentials
 
+#### Option A — scripted (recommended)
+
+```bash
+npm run auth               # prints the CKAT value to the console
+npm run auth -- .env       # writes CK_COOKIES=<ckat> to .env
+```
+
+Launches Chrome with a dedicated profile at `~/.creditkarma-mcp/chrome-profile`, waits for you to sign in at creditkarma.com, then captures the `CKAT` cookie (the URL-encoded bundle of access + refresh JWTs). Either prints it (for pasting into Claude Desktop / MCPB) or writes it to the env file you pass. Requires Google Chrome installed locally; the script installs `puppeteer-core` on first run (~1 MB).
+
+#### Option B — manual (DevTools)
+
 1. Log in to [creditkarma.com](https://www.creditkarma.com) in Chrome
 2. Open DevTools → **Application** → **Cookies** → `https://www.creditkarma.com`
 3. Find the `CKAT` cookie and copy its value
 
 ### Setting credentials
 
-Call `ck_set_session` with your cookie value — it accepts any of:
+Either of these works:
+
+- Paste the value from `npm run auth` (or your CKAT cookie) into `CK_COOKIES` in your `.env` or Claude config
+- Or call `ck_set_session` from within Claude with the cookie value — it accepts any of:
 
 | Format | Example |
 |--------|---------|
 | Raw CKAT value | `eyJraWQ...%3BeyJraWQ...` |
 | `CKAT=<value>` | `CKAT=eyJraWQ...%3BeyJraWQ...` |
-| Full Cookie header | *(paste the entire Cookie header from DevTools → Network)* |
-
-Or set `CK_COOKIES` directly in your `.env` file (any of the three formats above).
+| Full Cookie header | *(what `npm run auth` prints)* |
 
 The server automatically extracts both the access token and refresh token from the CKAT cookie, and refreshes the access token as needed.
 
@@ -103,7 +116,7 @@ The server automatically extracts both the access token and refresh token from t
 
 - **Access token**: ~15 minutes (auto-refreshed transparently)
 - **Refresh token**: ~8 hours
-- When the refresh token expires, log in to creditkarma.com again, grab the new CKAT cookie, and call `ck_set_session`
+- When the refresh token expires, re-run `npm run auth` (or grab the new CKAT cookie from DevTools) and either update `CK_COOKIES` or call `ck_set_session`
 
 ## Available tools
 
@@ -145,7 +158,7 @@ sync_state   (key, value)
 
 ## Troubleshooting
 
-**"TOKEN_EXPIRED"** — your refresh token has expired. Log in to creditkarma.com, grab the new CKAT cookie, and call `ck_set_session`.
+**"TOKEN_EXPIRED"** — your refresh token has expired. Re-run `npm run auth` (or grab a new CKAT cookie) and update `CK_COOKIES` or call `ck_set_session`.
 
 **Sync returns 0 transactions** — check that your `CK_COOKIES` value is fresh. CKAT cookies expire after ~8 hours.
 

package/SKILL.md

@@ -58,6 +58,15 @@ Or use a `.env` file in the project directory with `CK_COOKIES=<value>`.
 
 ### Getting CK_COOKIES
 
+**Scripted (recommended — source install):**
+```bash
+npm run auth               # prints the CKAT value to the console
+npm run auth -- .env       # writes CK_COOKIES=<ckat> to .env
+```
+
+Launches Chrome with a dedicated profile, waits for sign-in at creditkarma.com, then captures the `CKAT` cookie (the URL-encoded bundle of access + refresh JWTs). Use the printed value with Claude Desktop / MCPB, or the `.env` form when running from source.
+
+**Manual (DevTools):**
 1. Log in to [creditkarma.com](https://www.creditkarma.com) in Chrome
 2. DevTools → **Application** → **Cookies** → `creditkarma.com`
 3. Copy the `CKAT` cookie value
@@ -70,7 +79,7 @@ Call `ck_set_session` with your cookie value to store credentials and enable aut
 
 - Access token: ~15 min TTL, auto-refreshed transparently
 - Refresh token: ~8 hours TTL
-- When expired: log in to creditkarma.com, grab the new CKAT cookie, call `ck_set_session`
+- When expired: re-run `npm run auth` (or grab a new CKAT cookie) and call `ck_set_session`
 
 ## Tools
 
@@ -97,10 +106,9 @@ Call `ck_set_session` with your cookie value to store credentials and enable aut
 ## Workflows
 
 **First-time setup:**
-1. Log in to [creditkarma.com](https://www.creditkarma.com) in Chrome
-2. DevTools → Application → Cookies → copy the `CKAT` value
-3. `ck_set_session(cookies)` → credentials stored
-4. `ck_sync_transactions` → initial full sync
+1. Run `npm run auth` (or grab the `CKAT` cookie manually from creditkarma.com DevTools)
+2. Paste into `CK_COOKIES` env var, or call `ck_set_session(cookies)` from within Claude
+3. `ck_sync_transactions` → initial full sync
 
 **Regular use:**
 - `ck_sync_transactions` → pull latest transactions

package/dist/bundle.js

@@ -30430,7 +30430,7 @@ function registerAuthTools(server, ctx) {
   server.registerTool(
     "ck_set_session",
     {
-      description: 'Store a Credit Karma session to enable automatic token refresh. Accepts any of: (1) the raw CKAT cookie value, (2) the full Cookie header string from any creditkarma.com request, or (3) just "CKAT=<value>". Find CKAT in Chrome DevTools \u2192 Application \u2192 Cookies \u2192 creditkarma.com, or copy the Cookie request header from the Network tab.',
+      description: 'Store a Credit Karma session to enable automatic token refresh. Accepts any of: (1) the raw CKAT cookie value, (2) the full Cookie header string from any creditkarma.com request, or (3) just "CKAT=<value>". Capture via `npm run auth` from the creditkarma-mcp repo, or find CKAT in Chrome DevTools \u2192 Application \u2192 Cookies \u2192 creditkarma.com.',
       annotations: { readOnlyHint: false },
       inputSchema: {
         cookies: external_exports3.string().describe('One of: raw CKAT value, full Cookie header string, or "CKAT=<value>"')
@@ -30523,7 +30523,7 @@ async function handleSyncTransactions(args, ctx) {
 }
 async function refreshOrThrow(ctx) {
   if (!ctx.client.getRefreshToken()) {
-    throw new Error("TOKEN_EXPIRED: No valid token. Call ck_set_session with your CKAT cookie to authenticate.");
+    throw new Error("TOKEN_EXPIRED: No valid token. Run `npm run auth` to capture a fresh Cookie header via browser login, or call ck_set_session with your CKAT cookie.");
   }
   await ctx.client.refreshAccessToken();
 }
@@ -30859,7 +30859,7 @@ async function main() {
     mcpJsonPath
   };
   const server = new McpServer(
-    { name: "creditkarma-mcp", version: "2.0.1" }
+    { name: "creditkarma-mcp", version: "2.0.3" }
   );
   registerAuthTools(server, ctx);
   registerSyncTools(server, ctx);

package/dist/index.js

@@ -40,7 +40,7 @@ async function main() {
         db: initDb(dbPath),
         mcpJsonPath
     };
-    const server = new McpServer({ name: 'creditkarma-mcp', version: '2.0.1' });
+    const server = new McpServer({ name: 'creditkarma-mcp', version: '2.0.3' });
     registerAuthTools(server, ctx);
     registerSyncTools(server, ctx);
     registerQueryTools(server, ctx);

package/dist/tools/auth.js

@@ -56,7 +56,7 @@ export function persistSession(cookies, mcpJsonPath) {
 export const persistTokens = persistSession;
 export function registerAuthTools(server, ctx) {
     server.registerTool('ck_set_session', {
-        description: 'Store a Credit Karma session to enable automatic token refresh. Accepts any of: (1) the raw CKAT cookie value, (2) the full Cookie header string from any creditkarma.com request, or (3) just "CKAT=<value>". Find CKAT in Chrome DevTools \u2192 Application \u2192 Cookies \u2192 creditkarma.com, or copy the Cookie request header from the Network tab.',
+        description: 'Store a Credit Karma session to enable automatic token refresh. Accepts any of: (1) the raw CKAT cookie value, (2) the full Cookie header string from any creditkarma.com request, or (3) just "CKAT=<value>". Capture via `npm run auth` from the creditkarma-mcp repo, or find CKAT in Chrome DevTools \u2192 Application \u2192 Cookies \u2192 creditkarma.com.',
         annotations: { readOnlyHint: false },
         inputSchema: {
             cookies: z.string().describe('One of: raw CKAT value, full Cookie header string, or "CKAT=<value>"'),

package/dist/tools/sync.js

@@ -96,7 +96,7 @@ export async function handleSyncTransactions(args, ctx) {
 }
 async function refreshOrThrow(ctx) {
     if (!ctx.client.getRefreshToken()) {
-        throw new Error('TOKEN_EXPIRED: No valid token. Call ck_set_session with your CKAT cookie to authenticate.');
+        throw new Error('TOKEN_EXPIRED: No valid token. Run `npm run auth` to capture a fresh Cookie header via browser login, or call ck_set_session with your CKAT cookie.');
     }
     await ctx.client.refreshAccessToken();
 }

package/package.json

@@ -1,12 +1,27 @@
 {
   "name": "creditkarma-mcp",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "MCP server for Credit Karma — natural-language access to your transactions, spending, and accounts",
-  "author": "Claude Sonnet 4.6 (AI) <https://www.anthropic.com/claude>",
+  "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/chrischall/creditkarma-mcp.git"
   },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "ai",
+    "credit-karma",
+    "transactions",
+    "spending",
+    "accounts",
+    "budgeting",
+    "personal-finance",
+    "sqlite",
+    "graphql"
+  ],
   "type": "module",
   "bin": {
     "creditkarma-mcp": "dist/index.js"
@@ -20,6 +35,7 @@
     "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --outfile=dist/bundle.js",
     "start": "node dist/index.js",
     "dev": "node --env-file=.env dist/index.js",
+    "auth": "node scripts/setup-auth.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage"
@@ -33,6 +49,7 @@
     "@types/node": "^25.5.2",
     "@vitest/coverage-v8": "^4.1.2",
     "esbuild": "^0.28.0",
+    "puppeteer-core": "^24.0.0",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2"
   }