Koko Credit card assistant MCP Server

क्रेडिट कार्ड खोजने, तुलना करने और अनुकूलित करने के लिए कोको के क्रेडिट कार्ड वर्कफ़्लो तक पहुँचने वाला MCP सर्वर

दस्तावेज़

KoKo Finance MCP Server

A hosted MCP server for AI-powered credit card advice. Search 100+ US credit cards, compare options side by side, analyze portfolio health, and get personalized recommendations — all through the Model Context Protocol.

Server URL: https://kokofinance.net/mcp/

No API key required. No local installation needed. Just connect your MCP client.

Quick Setup

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "koko-finance": {
      "type": "http",
      "url": "https://kokofinance.net/mcp/"
    }
  }
}

Claude Code

claude mcp add koko-finance --transport http https://kokofinance.net/mcp/

Or copy the .mcp.json from this repo into your project.

Cursor

Go to Settings > MCP and add a new server:

Name: koko-finance
Type: HTTP
URL: https://kokofinance.net/mcp/

Cline / Windsurf

Add to your MCP settings file:

{
  "mcpServers": {
    "koko-finance": {
      "type": "http",
      "url": "https://kokofinance.net/mcp/"
    }
  }
}

Tools (14)

Tool	Description
`search_credit_cards`	Natural language search across 100+ US credit cards. Optional filters: `card_type`, `issuer`, `max_annual_fee`, `credit_tier`
`compare_cards`	Side-by-side comparison of 2-3 cards with fees, rewards, net value, and break-even. Optional: `credit_tier`, `primary_goal`, `issuer_preferences` (<100ms)
`get_card_details`	Full details for a specific card (fees, rewards, benefits)
`calculate_card_value`	Annual fee break-even analysis with first-year and ongoing value
`optimize_portfolio`	Portfolio health score, per-card KEEP/OPTIMIZE/CANCEL verdicts. Optional: `point_balances`, `benefit_selections`, `credit_tier`, `primary_goal`, `issuer_preferences`, `analysis_type`, `cancel_threshold`, `keep_threshold` (<100ms)
`recommend_card_for_category`	Best card to use for a specific spending category, ranked by reward value. Optional: `spending`, `credit_tier`, `primary_goal`, `issuer_preferences` (<100ms)
`check_card_renewal`	Should you renew this card? Verdict + downgrade/replacement options. Optional: `benefit_selections`, `acquired_date`, `credit_tier`, `primary_goal`, `renewal_cancel_threshold`, `renewal_keep_threshold`
`create_mcp_session`	Session tracking for multi-query conversations
`which_card_at_merchant`	Best card from your portfolio at a specific merchant. Auto-detects spending category (e.g. Starbucks → dining) and ranks by reward value
`check_merchant_benefits`	Check if any cards have credits at a merchant (e.g. Saks → Amex Platinum $100 credit). Includes earning recommendation
`get_card_benefits`	All credits/benefits for a card with value, frequency, schedule, and conditions
`get_card_terms`	Schumer Box data — purchase APR, penalty APR, late fees, cash advance fees, promotional APR, grace period
`get_card_changes`	Audit log of card data changes (fee updates, benefit changes) with date filtering. Optional: `field` filter
`get_program_trends`	Points program valuation history — CPP and transfer partner ratio changes over time

Personalization Parameters

Several tools accept optional parameters that improve result relevance. All are optional — when omitted, the server uses sensible defaults (e.g., national average spending, no issuer bias).

`credit_tier`

Credit score range that affects card eligibility and approval likelihood.

Value	Meaning
`"excellent"`	750+
`"good"`	700-749
`"fair"`	650-699
`"poor"`	Below 650

Used by: search_credit_cards, compare_cards, optimize_portfolio, recommend_card_for_category, check_card_renewal

`primary_goal`

The user's main objective for their credit card strategy.

Value	Meaning
`"maximize_rewards"`	Get the most points/cashback from everyday spending
`"minimize_fees"`	Keep annual fees low while maintaining value
`"build_credit"`	Establish or improve credit score
`"travel_perks"`	Prioritize lounge access, travel credits, and transfer partners
`"simplicity"`	Prefer fewer cards with straightforward reward structures

Used by: compare_cards, optimize_portfolio, recommend_card_for_category, check_card_renewal

`issuer_preferences`

A list of issuer preference objects that express affinity or aversion toward specific card issuers. Each entry has an issuer name and a weight between -1.0 (strong aversion) and 1.0 (strong preference).

[
  {"issuer": "Chase", "weight": 0.8},
  {"issuer": "American Express", "weight": 0.5},
  {"issuer": "Capital One", "weight": -0.5}
]

Used by: compare_cards, optimize_portfolio, recommend_card_for_category

`spending`

A dictionary of monthly spending amounts by category, used to calculate personalized reward values instead of national averages.

{"dining": 500, "groceries": 800, "travel": 300, "gas": 150, "general": 2000}

Used by: compare_cards, optimize_portfolio, recommend_card_for_category, check_card_renewal, calculate_card_value

`cancel_threshold` / `keep_threshold`

Override the default net-value thresholds (in dollars) for KEEP/OPTIMIZE/CANCEL verdicts.

cancel_threshold — Cards below this → CANCEL (default: -50)
keep_threshold — Cards above this → KEEP (default: 50)

Used by: optimize_portfolio

`renewal_cancel_threshold` / `renewal_keep_threshold`

Same concept applied to a single card's renewal decision.

Used by: check_card_renewal

`acquired_date`

Date the user acquired the card (YYYY-MM-DD). Informs tenure-based renewal analysis.

Used by: check_card_renewal

Response Metadata

Calculation tools include metadata fields in responses:

spending_source — "user_provided" or "national_averages". Indicates whether calculations used user-supplied spending or BLS national averages.
data_source — Indicates where card data was sourced (e.g., "koko_db").
rewards_by_category — Per-category reward breakdown included in compare, portfolio, and value tools.
points_program_key / portal_cpp — Points program identifier and portal cents-per-point valuation, included on all card data.

Prompts (5)

Pre-built conversation starters that guide the AI through structured workflows:

Prompt	Description	Parameters
`portfolio-review`	Full portfolio analysis with health score and verdicts	`card_names`, `monthly_spending` (optional)
`which-card`	Find the best card for a specific purchase	`card_names`, `category`, `amount` (optional)
`new-card-finder`	Search for a new card matching your criteria	`spending_focus`, `annual_fee_limit` (optional), `credit_score` (optional)
`renewal-check`	Walk through a card renewal decision step by step	`card_name`, `annual_fee` (optional)
`card-risk-assessment`	Analyze a card's risk profile — APR exposure, penalty triggers, fee traps	`card_name`, `issuer` (optional)

Benefit Selections

The optimize_portfolio and check_card_renewal tools accept a benefit_selections parameter — a list of individual benefit keys the user actually uses. Selected benefits count at 100% utilization; unselected benefits count at 0%.

benefit_selections: ["uber", "airline_fee", "dining", "admirals_club"]

This gives accurate net-value calculations instead of the default 50% utilization estimate.

Discover valid keys by calling the REST endpoint GET https://kokofinance.net/api/v1/benefit-categories (no auth required), or see the developer docs.

Example Conversations

"Review my portfolio"

I have a Chase Sapphire Reserve, Amex Gold, and Citi Double Cash. Analyze my portfolio and tell me which cards are worth keeping.

"Which card should I use?"

I'm buying $200 in groceries. I have an Amex Gold, Chase Freedom Unlimited, and Citi Custom Cash. Which card should I use?

"Find me a new card"

I spend a lot on travel and dining. I want a card under $300 annual fee with a good sign-up bonus. What do you recommend?

"Should I renew my Amex Platinum?"

I only use the Uber credit and airline fee credit on my Amex Platinum. Is it still worth paying the $695 annual fee?

"Which card at Starbucks?"

I'm buying coffee at Starbucks. I have a Chase Sapphire Reserve, Amex Gold, and Citi Double Cash. Which card earns the most?

"Do I have any credits at Saks?"

I'm shopping at Saks Fifth Avenue. Do any of my cards have credits there? I have an Amex Platinum and Chase Sapphire Reserve.

"What benefits does my Amex Platinum have?"

Show me all the credits and benefits on my Amex Platinum card — how much is each worth?

Screenshots

Screenshots captured from Claude using the KoKo Finance MCP server.

1. Search for Credit Cards

"Find me the best travel credit cards under $300 annual fee"

2. Compare Cards Side by Side

"Compare Chase Sapphire Reserve and Amex Gold"

Compare cards — part 1 Compare cards — part 2

3. Portfolio Review

"Analyze my portfolio: Chase Sapphire Reserve, Amex Gold, Citi Double Cash"

Portfolio review — part 1 Portfolio review — part 2

4. Which Card at a Merchant

"Which card should I use at Starbucks?"

Which card at merchant

5. Card Benefits Breakdown

"Show me all the credits and benefits on my Amex Platinum"

Card benefits — part 1 Card benefits — part 2

Also Available

Claude Code Plugin — Adds the MCP server connection plus an Agent Skill that teaches Claude structured credit card workflows

Privacy Policy

KoKo Finance collects minimal data required to operate the MCP server:

Authentication data: Google OAuth profile (name, email) when you sign in. No sign-in is required for free-tier usage.
Usage logs: Tool name, parameters, success/failure status, and timestamp for each MCP tool call. Used for rate limiting and service improvement.
No third-party sharing: We do not sell or share personal data with third parties.
Data retention: Usage logs are retained for service operation. You can request deletion by contacting us.
Contact: [email protected]

Full privacy policy: https://kokofinance.net/privacy.html

License

MIT