KoKo Finance — Credit Card Advisor
AI credit card advisor - search cards, compare portfolios, and optimize rewards
Open source Repository Open in the app JSON README (API)
About
AI credit card advisor - search cards, compare portfolios, and optimize rewards
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- net.kokofinance
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.1.0
- Stars
- 1
- Last push
- 2026-09-05T15:56:54Z
- Repository state
- ativo
- License
- MIT
- Added
- 2026-08-29 04:01:49
- Updated
- 2026-08-29 15:00:29
- Origin id
net.kokofinance/koko-finance
README
# 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):
```json
{
"mcpServers": {
"koko-finance": {
"type": "http",
"url": "https://kokofinance.net/mcp/"
}
}
}
```
### Claude Code
```bash
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:
```json
{
"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` 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`.
```json
[
{"issuer": "Chase", "weight": 1.5},
{"issuer": "American Express", "weight": 1.2},
{"issuer": "Capital One", "weight": 0.3}
]
```
**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.
```json
{"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: -200)
- `keep_threshold` — Cards above this → KEEP (default: 100)
**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](https://kokofinance.net/developers.html#benefit-categories).
## 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"
### 3. Portfolio Review
> "Analyze my portfolio: Chase Sapphire Reserve, Amex Gold, Citi Double Cash"
### 4. Which Card at a Merchant
> "Which card should I use at Starbucks?"
### 5. Card Benefits Breakdown
> "Show me all the credits and benefits on my Amex Platinum"
## Links
- [KoKo Finance](https://kokofinance.net) — Main site
- [Developer Documentation](https://kokofinance.net/developers.html) — Full API and tool reference
- [MCP Endpoint](https://kokofinance.net/mcp/) — Direct server URL
## Also Available
- **[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
## 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**: [privacy@kokofinance.net](mailto:privacy@kokofinance.net)
Full privacy policy: [https://kokofinance.net/privacy.html](https://kokofinance.net/privacy.html)
## License
MIT