{
  "markdown": "# KoKo Finance MCP Server\n\nA 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.\n\n**Server URL:** `https://kokofinance.net/mcp/`\n\nNo API key required. No local installation needed. Just connect your MCP client.\n\n## Quick Setup\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"koko-finance\": {\n      \"type\": \"http\",\n      \"url\": \"https://kokofinance.net/mcp/\"\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add koko-finance --transport http https://kokofinance.net/mcp/\n```\n\nOr copy the `.mcp.json` from this repo into your project.\n\n### Cursor\n\nGo to **Settings > MCP** and add a new server:\n- **Name:** koko-finance\n- **Type:** HTTP\n- **URL:** `https://kokofinance.net/mcp/`\n\n### Cline / Windsurf\n\nAdd to your MCP settings file:\n\n```json\n{\n  \"mcpServers\": {\n    \"koko-finance\": {\n      \"type\": \"http\",\n      \"url\": \"https://kokofinance.net/mcp/\"\n    }\n  }\n}\n```\n\n## Tools (14)\n\n| Tool | Description |\n|------|-------------|\n| `search_credit_cards` | Natural language search across 100+ US credit cards. Optional filters: `card_type`, `issuer`, `max_annual_fee`, `credit_tier` |\n| `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) |\n| `get_card_details` | Full details for a specific card (fees, rewards, benefits) |\n| `calculate_card_value` | Annual fee break-even analysis with first-year and ongoing value |\n| `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) |\n| `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) |\n| `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` |\n| `create_mcp_session` | Session tracking for multi-query conversations |\n| `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 |\n| `check_merchant_benefits` | Check if any cards have credits at a merchant (e.g. Saks → Amex Platinum $100 credit). Includes earning recommendation |\n| `get_card_benefits` | All credits/benefits for a card with value, frequency, schedule, and conditions |\n| `get_card_terms` | Schumer Box data — purchase APR, penalty APR, late fees, cash advance fees, promotional APR, grace period |\n| `get_card_changes` | Audit log of card data changes (fee updates, benefit changes) with date filtering. Optional: `field` filter |\n| `get_program_trends` | Points program valuation history — CPP and transfer partner ratio changes over time |\n\n## Personalization Parameters\n\nSeveral 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).\n\n### `credit_tier`\n\nCredit score range that affects card eligibility and approval likelihood.\n\n| Value | Meaning |\n|-------|---------|\n| `\"excellent\"` | 750+ |\n| `\"good\"` | 700-749 |\n| `\"fair\"` | 650-699 |\n| `\"poor\"` | Below 650 |\n\n**Used by:** `search_credit_cards`, `compare_cards`, `optimize_portfolio`, `recommend_card_for_category`, `check_card_renewal`\n\n### `primary_goal`\n\nThe user's main objective for their credit card strategy.\n\n| Value | Meaning |\n|-------|---------|\n| `\"maximize_rewards\"` | Get the most points/cashback from everyday spending |\n| `\"minimize_fees\"` | Keep annual fees low while maintaining value |\n| `\"build_credit\"` | Establish or improve credit score |\n| `\"travel_perks\"` | Prioritize lounge access, travel credits, and transfer partners |\n| `\"simplicity\"` | Prefer fewer cards with straightforward reward structures |\n\n**Used by:** `compare_cards`, `optimize_portfolio`, `recommend_card_for_category`, `check_card_renewal`\n\n### `issuer_preferences`\n\nA list of issuer preference objects that express affinity or aversion toward specific card issuers. Each entry has an `issuer` name and a `weight` that multiplies the card's ranking score — `1.0` is neutral (the default for any issuer not listed), values above `1.0` boost, values below `1.0` de-boost. Valid range is `0.1` to `3.0`.\n\n```json\n[\n  {\"issuer\": \"Chase\", \"weight\": 1.5},\n  {\"issuer\": \"American Express\", \"weight\": 1.2},\n  {\"issuer\": \"Capital One\", \"weight\": 0.3}\n]\n```\n\n**Used by:** `compare_cards`, `optimize_portfolio`, `recommend_card_for_category`\n\n### `spending`\n\nA dictionary of monthly spending amounts by category, used to calculate personalized reward values instead of national averages.\n\n```json\n{\"dining\": 500, \"groceries\": 800, \"travel\": 300, \"gas\": 150, \"general\": 2000}\n```\n\n**Used by:** `compare_cards`, `optimize_portfolio`, `recommend_card_for_category`, `check_card_renewal`, `calculate_card_value`\n\n### `cancel_threshold` / `keep_threshold`\n\nOverride the default net-value thresholds (in dollars) for KEEP/OPTIMIZE/CANCEL verdicts.\n\n- `cancel_threshold` — Cards below this → CANCEL (default: -200)\n- `keep_threshold` — Cards above this → KEEP (default: 100)\n\n**Used by:** `optimize_portfolio`\n\n### `renewal_cancel_threshold` / `renewal_keep_threshold`\n\nSame concept applied to a single card's renewal decision.\n\n**Used by:** `check_card_renewal`\n\n### `acquired_date`\n\nDate the user acquired the card (`YYYY-MM-DD`). Informs tenure-based renewal analysis.\n\n**Used by:** `check_card_renewal`\n\n## Response Metadata\n\nCalculation tools include metadata fields in responses:\n\n- **`spending_source`** — `\"user_provided\"` or `\"national_averages\"`. Indicates whether calculations used user-supplied spending or BLS national averages.\n- **`data_source`** — Indicates where card data was sourced (e.g., `\"koko_db\"`).\n- **`rewards_by_category`** — Per-category reward breakdown included in compare, portfolio, and value tools.\n- **`points_program_key`** / **`portal_cpp`** — Points program identifier and portal cents-per-point valuation, included on all card data.\n\n## Prompts (5)\n\nPre-built conversation starters that guide the AI through structured workflows:\n\n| Prompt | Description | Parameters |\n|--------|-------------|------------|\n| `portfolio-review` | Full portfolio analysis with health score and verdicts | `card_names`, `monthly_spending` (optional) |\n| `which-card` | Find the best card for a specific purchase | `card_names`, `category`, `amount` (optional) |\n| `new-card-finder` | Search for a new card matching your criteria | `spending_focus`, `annual_fee_limit` (optional), `credit_score` (optional) |\n| `renewal-check` | Walk through a card renewal decision step by step | `card_name`, `annual_fee` (optional) |\n| `card-risk-assessment` | Analyze a card's risk profile — APR exposure, penalty triggers, fee traps | `card_name`, `issuer` (optional) |\n\n## Benefit Selections\n\nThe `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%.\n\n```\nbenefit_selections: [\"uber\", \"airline_fee\", \"dining\", \"admirals_club\"]\n```\n\nThis gives accurate net-value calculations instead of the default 50% utilization estimate.\n\n**Discover valid keys** by calling the REST endpoint `GET https://kokofinance.net/api/v1/benefit-categories` (no auth required), or see the [developer docs](https://kokofinance.net/developers.html#benefit-categories).\n\n## Example Conversations\n\n**\"Review my portfolio\"**\n> I have a Chase Sapphire Reserve, Amex Gold, and Citi Double Cash. Analyze my portfolio and tell me which cards are worth keeping.\n\n**\"Which card should I use?\"**\n> I'm buying $200 in groceries. I have an Amex Gold, Chase Freedom Unlimited, and Citi Custom Cash. Which card should I use?\n\n**\"Find me a new card\"**\n> 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?\n\n**\"Should I renew my Amex Platinum?\"**\n> I only use the Uber credit and airline fee credit on my Amex Platinum. Is it still worth paying the $695 annual fee?\n\n**\"Which card at Starbucks?\"**\n> I'm buying coffee at Starbucks. I have a Chase Sapphire Reserve, Amex Gold, and Citi Double Cash. Which card earns the most?\n\n**\"Do I have any credits at Saks?\"**\n> I'm shopping at Saks Fifth Avenue. Do any of my cards have credits there? I have an Amex Platinum and Chase Sapphire Reserve.\n\n**\"What benefits does my Amex Platinum have?\"**\n> Show me all the credits and benefits on my Amex Platinum card — how much is each worth?\n\n## Screenshots\n\nScreenshots captured from Claude using the KoKo Finance MCP server.\n\n### 1. Search for Credit Cards\n\n> \"Find me the best travel credit cards under $300 annual fee\"\n\n![Search travel cards](screenshots/01-search-travel-cards.png)\n\n### 2. Compare Cards Side by Side\n\n> \"Compare Chase Sapphire Reserve and Amex Gold\"\n\n![Compare cards — part 1](screenshots/02-compare-cards-part1.png)\n![Compare cards — part 2](screenshots/02-compare-cards-part2.png)\n\n### 3. Portfolio Review\n\n> \"Analyze my portfolio: Chase Sapphire Reserve, Amex Gold, Citi Double Cash\"\n\n![Portfolio review — part 1](screenshots/03-portfolio-review-part1.png)\n![Portfolio review — part 2](screenshots/03-portfolio-review-part2.png)\n\n### 4. Which Card at a Merchant\n\n> \"Which card should I use at Starbucks?\"\n\n![Which card at merchant](screenshots/04-which-card-at-merchant.png)\n\n### 5. Card Benefits Breakdown\n\n> \"Show me all the credits and benefits on my Amex Platinum\"\n\n![Card benefits — part 1](screenshots/05-card-benefits-part1.png)\n![Card benefits — part 2](screenshots/05-card-benefits-part2.png)\n\n## Links\n\n- [KoKo Finance](https://kokofinance.net) — Main site\n- [Developer Documentation](https://kokofinance.net/developers.html) — Full API and tool reference\n- [MCP Endpoint](https://kokofinance.net/mcp/) — Direct server URL\n\n## Also Available\n\n- **[Claude Code Plugin](https://github.com/KokoFinance/koko-credit-card-plugin)** — Adds the MCP server connection plus an Agent Skill that teaches Claude structured credit card workflows\n\n## Privacy Policy\n\nKoKo Finance collects minimal data required to operate the MCP server:\n\n- **Authentication data**: Google OAuth profile (name, email) when you sign in. No sign-in is required for free-tier usage.\n- **Usage logs**: Tool name, parameters, success/failure status, and timestamp for each MCP tool call. Used for rate limiting and service improvement.\n- **No third-party sharing**: We do not sell or share personal data with third parties.\n- **Data retention**: Usage logs are retained for service operation. You can request deletion by contacting us.\n- **Contact**: [privacy@kokofinance.net](mailto:privacy@kokofinance.net)\n\nFull privacy policy: [https://kokofinance.net/privacy.html](https://kokofinance.net/privacy.html)\n\n## License\n\nMIT\n",
  "bytes": 11445,
  "sha": "f51d340f3270dba673bc6fc24a1e1d35b59754919ae7cfacc30d09cfc18500b6",
  "repo_slug": "kokofinance/koko-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_net_kokofinance_koko_finance_e5ebcc04/readme"
}