Ask Claude, ChatGPT, Cursor, Windsurf, or any MCP client about your finances.
Easiest way to connect
No config files, no API keys to paste. Just click, log in, and authorize. You'll be done in under a minute. Works on claude.ai in any browser, and on the Claude iOS / Android app.
Open Claude on the web or mobile
Go to claude.ai or open the Claude app on your phone. Start a new conversation or open any existing one.
Click the plus icon in the chat input
Or go to Settings → Integrations and click Add custom integration.
Fill in the connector details
Finlynqhttp://localhost:3000/api/mcpClick Add, then Connect
Claude will open a Finlynq authorization page. Log in if prompted, then click Allow to grant access.
You're connected!
The Finlynq tools are now available in every Claude conversation. Try one of these:
Privacy note:Claude Web uses OAuth 2.1, so your Finlynq passphrase and financial data are never shared with Anthropic. Only the tool responses (query results) pass through Claude's servers.
Click any prompt to copy it, then paste into your AI assistant.
Paste any of these into Claude to watch a preview / confirm / execute flow run end-to-end. Claude always asks before it commits anything destructive.
Capability groups below; for the exhaustive name-by-name list (with category, transport, and OAuth scope per tool) see the full MCP tool catalog. Or use /api-docs / /.well-known/mcp.json for the JSON-Schema view.
Drop a CSV or OFX into Finlynq with the Upload button, then ask Claude to take it from there. Claude lists pending uploads, shows you a preview with duplicate detection, and only commits once you confirm.
list_pending_uploadspreview_importexecute_importcancel_importRecategorize, retag, or delete many transactions at once. Every bulk operation runs in two steps: a preview that returns a sample and a signed confirmation token, then an execute call that commits. Claude can't skip the confirmation, since the token is scoped to the exact payload.
preview_bulk_updateexecute_bulk_updatepreview_bulk_deleteexecute_bulk_deletepreview_bulk_categorizeexecute_bulk_categorizeDetect recurring charges from your transaction history, then add, update (pause/resume/cancel via status), or delete subscriptions without leaving the chat.
list_subscriptionsdetect_subscriptionsbulk_add_subscriptionsadd_subscriptionupdate_subscriptiondelete_subscriptionget_subscription_summaryTrack balances, generate amortization schedules, and compare avalanche vs. snowball payoff plans across all your loans.
list_loansadd_loanupdate_loandelete_loanget_loan_amortizationget_debt_payoff_planAsk for live or historical FX rates, convert amounts between currencies, or pin your own rate overrides for bookkeeping.
get_fx_rateconvert_amountlist_fx_overridesset_fx_overridedelete_fx_overrideSplit a single transaction across multiple categories. Handy for $200 grocery runs that include household goods, or Costco trips that mix food and electronics.
list_splitsadd_splitupdate_splitdelete_splitreplace_splitsCreate, list, reorder, test, and delete auto-categorization rules. Dry-run any rule against your history before you apply it.
list_rulescreate_ruleupdate_ruledelete_ruletest_rulereorder_rulesapply_rules_to_uncategorizedManually create, rename, move, or delete portfolio positions (the import pipeline auto-creates them from CSV/ZIP, but for one-offs these are what you want). Plus the read tools for portfolio metrics, performance, a deep-dive on a single position, and rebalancing/benchmark insights. Renames cascade to all transactions automatically; deletes leave the transactions in place with the holding link cleared.
add_portfolio_holdingupdate_portfolio_holdingdelete_portfolio_holdingget_portfolio_analysisget_portfolio_performanceanalyze_holdingtrace_holding_quantityget_investment_insightsAdd or update accounts, including a short alias (e.g. last 4 digits of a card, or a receipt label) so Claude can match a transaction even when the source document doesn't use the canonical name. The account parameter on every write tool fuzzy-matches your account names and exact-matches aliases, so pass either one.
add_accountupdate_accountdelete_accountget_account_balancesBefore recording a transaction, ask Claude to guess the right category and tags based on your rules and history.
suggest_transaction_detailsBalances, net worth, budgets, goals, spending trends, income statements, health score, spotlight alerts, weekly recap, cash flow forecast, anomalies. Every dashboard, queryable in natural language. Portfolio metrics live in the Portfolio holdings card above.
get_account_balancesget_net_worthsearch_transactionsget_budget_summaryget_spending_trendsget_income_statementget_goalsget_cash_flow_forecastget_recurring_transactionsget_spotlight_itemsget_weekly_recapget_spending_anomaliesget_financial_health_scoreget_categoriesfinlynq_helpHow destructive ops stay safe:bulk updates, deletes, imports, and subscription-detection all use a preview → confirm → execute pattern. The preview returns a signed token scoped to the exact payload; the execute step rejects unless the token matches. Claude can't skip the preview, and it can't mutate the payload between steps without invalidating the token.
Common issues and fixes when connecting an AI assistant to Finlynq. Click any item to expand.
DEPLOY_GENERATION on every release, which force-logs out in-flight tokens for security. Re-OAuth and you're back in within seconds.HTTP 401 Unauthorized from /api/mcp▾mcp-remote), delete ~/.mcp-auth and restart the app to re-run the approval. For Cursor / Windsurf using API-key auth, generate a fresh key at finlynq.com/settings/account and replace the old one in your client config.Symptom: the browser opens the approval page over and over, each time succeeding, and the tools never appear. The mcp-remote log shows repeating UnauthorizedError in _startOrAuthSse.
This was a server-side bug, fixed on 2026-07-24 (#318). GET /api/mcpanswered every request with 401, which the client read as “credentials rejected” and retried forever. It now correctly returns 405 Method Not Allowed.
If you're self-hosting: upgrade to an image built after that date, then delete ~/.mcp-auth and restart your client — the cached client registration predates the fix and will mask it. You should not need --static-oauth-client-metadata or --resource; if a guide told you to add them, they can now be removed.
localhost▾APP_URLto your public origin and restart. It is the single source of truth for the OAuth issuer, so when it's unset the server advertises http://localhost:3000 in its discovery documents — which works from the same machine and fails from everywhere else. Nothing in the client config can compensate for this; it has to be fixed server-side.Two scopes: mcp:read for read-only tools and mcp:write for anything that creates, edits, or deletes. Write implies read.
A client that requests no scope gets both — the default — and the consent screen always shows exactly what will be granted before you approve. Requesting mcp:readalone yields a read-only token that can see your data but never modify it, which is a reasonable choice if you only want analysis. Scopes the server doesn't recognize are ignored rather than rejected, so a client sending OIDC defaults still connects.
HTTP 403 Forbidden▾Originheader isn't on our allowlist. Custom MCP clients should send Origin as one of: claude.ai, claude.com, chatgpt.com, cursor.com, windsurf.dev, or codeium.com. CLI clients that send no Origin header at all are allowed through.HTTP 423 Locked▾portfolio_holding_id on every row in an is_investment=true account. Cash legs are auto-bound to a per-account Cash sleeve.DATABASE_URL and PF_USER_ID (a UUID matching a row in users.id). The stdio transport has no HTTP auth layer, so it binds to one user at process startup. Without PF_USER_ID the process exits 1 immediately.Issue not listed? Open a GitHub issue at github.com/finlynq/finlynq/issues. We triage daily.