kubera-3p-mcp

Typed TypeScript client for the Kubera (api.kubera.com) REST API, plus an MCP server that exposes those endpoints as tools.

Why does this exist?

Kubera has decided that if you have a white-label account (i.e. run by your financial advisor), you're not allowed to use their MCP Server to access your own financial data. So instead, we make our own and tell them to fly a kite.

Requirements

• Bun 1.1+ (for local development / prepare build)
• Node.js 18+ (to run the published bin bundle)

Install

bun install

Auth: cognito-session.json

Kubera API calls use:

Authorization: Bearer <Cognito AccessToken>

AccessTokens expire in about an hour. You provide a Cognito session file (refresh token, device fields, and your white-label baseUrl). Derived AccessTokens are cached on disk — same pattern as stonex-mcp — so Cognito refresh is not called on every tool use.

The session file also carries:

Field	Purpose
baseUrl	White-label host used for Origin / Referer (required)
apiBaseUrl	API root (optional; defaults to https://api.kubera.com/api/v1)
clientId	Cognito app client id (from Amplify localStorage)
userPoolId	Cognito user pool id (from access/id token iss)

Export session (one paste)

1. Log into your Kubera white-label host in the browser.
2. Open DevTools → Console.
3. Paste the contents of scripts/export-cognito-session.js and press Enter.
4. Save the downloaded cognito-session.json.
5. Run:

kubera-3p-mcp --session /path/to/cognito-session.json

AccessToken cache

OS	Path
Windows	%LOCALAPPDATA%\kubera-3p-mcp\access-token.json
macOS	~/Library/Caches/kubera-3p-mcp/access-token.json
Linux	${XDG_CACHE_HOME:-~/.cache}/kubera-3p-mcp/access-token.json

Startup / request flow:

1. Prefer a still-valid cached AccessToken.
2. Else, if the session export still has a valid AccessToken, cache that.
3. Else call Cognito REFRESH_TOKEN_AUTH once and write the new AccessToken to the cache.
4. On API 401, clear cache, refresh once, retry; if that fails, re-export the session file.

Treat the session file and cached token like passwords. Do not commit them.

Run the MCP server

bun start -- --session /path/to/cognito-session.json
# or after build:
node dist/kubera-3p-mcp.js --session /path/to/cognito-session.json

Cursor / Claude Desktop config

{
  "mcpServers": {
    "kubera": {
      "command": "npx",
      "args": [
        "-y",
        "kubera-3p-mcp",
        "--session",
        "C:/Users/YOU/cognito-session.json"
      ]
    }
  }
}

Local equivalent: "command": "bun", "args": ["run", "/path/to/kubera-3p-mcp/src/cli.ts", "--session", "/path/to/cognito-session.json"].

Typed client

import { KuberaClient } from "./src/client/index.ts";
import { resolveAuth } from "./src/auth/resolveAuth.ts";
import { writeTokenCache } from "./src/auth/tokenCache.ts";

const { accessToken, session } = await resolveAuth(
  "/path/to/cognito-session.json",
);

const client = new KuberaClient({
  accessToken,
  session,
  onAccessToken: (token) => writeTokenCache(token),
});

const user = await client.getUser();
const portfolios = await client.getPortfolios();
const portfolioId = portfolios.data.portfolio[0]!.id;
const chart = await client.getChartAndCagr({ portfolioId });

Capture fixtures

bun run capture -- --session ./cognito-session.json

Security note

Local capture files (kubera-fetch.js, kubera-har.json, kubera-urls.txt), cognito-session.json, and fixtures/ can contain live secrets and portfolio data. They are gitignored. Rotate credentials if those files were shared.