Skip to main content
Glama

SmartCard: Credit Card Rewards MCP Server

SmartCard is a Model Context Protocol (MCP) server that recommends the best credit card for every purchase. It tracks reward rates, monthly caps and cashback across your cards, so AI assistants like Claude Code and Claude Desktop can tell you which card to swipe.

Connect SmartCard to an AI assistant (Claude Desktop, Claude Code or any MCP client) and ask things like "Which card for ₹5,000 on Amazon?". The assistant calls SmartCard's tools, which know your cards, their reward rates, monthly caps and what you have already spent this cycle, and it answers with the card that gives the most back.

Features of the credit card recommendation server

  • Recommendations: ranks every card by the rupee value it returns on a purchase, including how much of each monthly cap you've already used.

  • Purchase log: records spends, calculates the rewards earned, and flags when another card would have earned more.

  • Reward balances: points or cashback earned, plus bonuses and redemptions, valued in rupees.

  • Spending report: spend and reward return by category and by card.

  • Card setup help: a web search tool and a guided prompt for entering a new card's reward terms.

Related MCP server: GetCurrentOffer MCP Server

Architecture

High-level design

The AI assistant (the MCP host) launches SmartCard as a subprocess and talks to it over stdio using the Model Context Protocol. Inside the server, each layer depends only on the one below it:

  1. Interface (server.py): 15 tools, 1 resource and 1 prompt with validated inputs and tool annotations.

  2. Service (wallet.py): every business operation, usable and testable without MCP.

  3. Engines (rewards.py, categories.py): pure reward maths and category intelligence, with no I/O.

  4. Storage (db.py): a single local SQLite file.

The only network call is the optional search_card_terms web lookup.

Request flow

What happens when you ask "Which card for ₹2,400 on Swiggy?":

sequenceDiagram
    autonumber
    actor U as User
    participant H as MCP host<br/>(Claude Code / Desktop)
    participant S as server.py<br/>MCP interface
    participant W as wallet.py<br/>Wallet service
    participant R as rewards.py<br/>Rewards engine
    participant D as SQLite
    U->>H: "Which card for ₹2,400 on Swiggy?"
    H->>S: tools/call recommend_card(amount=2400, merchant="Swiggy", channel="online")
    S->>W: recommend(...)
    W->>W: resolve category (Swiggy → dining)
    loop every card in the wallet
        W->>D: earn rates + cap usage this statement cycle
        D-->>W: rows
        W->>R: compute_earning(card, rates, cap_used)
        R-->>W: units, ₹ value, explanation
    end
    W-->>S: ranking, best first
    S-->>H: structured JSON result
    H-->>U: "Use Demo Foodie: 960 points = ₹240 back (10%)"

Modules

Module

Role

server.py

MCP tools, resource and prompt. Thin: validates input, formats output

wallet.py

All operations (cards, rates, purchases, balances, reports)

rewards.py

Pure reward calculation: rate matching, blocks, caps, billing cycles

db.py

SQLite schema and row mapping

categories.py

Spending categories, synonyms and merchant hints

models.py

Card, EarnRate, Purchase dataclasses

demo.py

Loads fictional demo cards

Built on the official MCP Python SDK 2.x (MCPServer). Every tool carries MCP tool annotations (read-only, writes, destructive, open-world) so clients know which calls need the user's approval. Expected failures are raised as ToolError, so the assistant sees a readable message such as "No card matches 'gold'" and can recover.

Earning model

Each card earns base_rate units for every block_inr rupees spent:

Card terms

reward_kind

base_rate

block_inr

unit_value_inr

1% cashback

cashback

1

100

1

4 points per ₹150, 1 pt = ₹0.50

points

4

150

0.5

Earn rates replace the base rate for a category, a merchant, or both, optionally only online or offline, and optionally with a monthly cap in units. When several rates match, the most specific wins (merchant > category > channel). Spend beyond a cap earns the base rate. Caps reset on the card's statement day. Categories in a card's exclusion list (by default fuel, rent, wallet loads and government payments) earn nothing.

Setup

Requires Python 3.12+ and uv.

git clone https://github.com/ShubhamK-2907/smartcard-mcp.git
cd smartcard-mcp
uv sync
uv run pytest                 # run the tests
uv run smartcard-demo         # optional: load three fictional cards to try it out

Data is stored in ~/.smartcard/smartcard.db. Set SMARTCARD_DB to use another file.

Connect to an AI assistant

Claude Code plugin (easiest). Installs the MCP server and the SmartCard skill, which teaches the agent when and how to use each tool:

/plugin install smartcard --marketplace ShubhamK-2907/smartcard-mcp

On older Claude Code versions, run /plugin marketplace add ShubhamK-2907/smartcard-mcp and then /plugin install smartcard@smartcard. Requires uv.

Claude Code (MCP server only)

claude mcp add smartcard -- uv --directory /absolute/path/to/smartcard run smartcard

Claude Desktop: add to ~/Library/Application Support/Claude/claude_desktop_config.json and restart the app:

{
  "mcpServers": {
    "smartcard": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/smartcard", "run", "smartcard"]
    }
  }
}

If the app can't find uv, use its full path (which uv).

To inspect the tools in a browser instead, run uv run mcp dev src/smartcard/server.py (MCP Inspector).

Tools

Tool

What it does

list_cards

Cards in the wallet with base rates

card_details

One card: earn rates, cap usage this cycle, balance

add_card, update_card, remove_card

Manage cards (remove_card asks for confirmation)

add_earn_rate, remove_earn_rate

Accelerated rates per category or merchant

recommend_card

Best card for a purchase, with a full ranking

log_purchase, list_purchases, delete_purchase

Purchase history

rewards_balance, adjust_rewards

Balances, bonuses and redemptions

spending_report

Spend and return by category and card

search_card_terms

Web search for a card's published reward terms

Also: the resource smartcard://categories and the prompt set_up_card.

Example conversation

You: Add my HDFC Millennia card Assistant runs search_card_terms, shows the terms, asks you to confirm, then calls add_card and add_earn_rate.

You: Which card for a ₹2,400 Swiggy order? recommend_card → "Demo Foodie: 960 points worth ₹240 (10%)."

You: I paid ₹2,400 at Swiggy with Demo Cashback log_purchase → logged, earned ₹72, and notes Demo Foodie would have given ₹168 more.

You: How am I doing this month? spending_report → spend and reward return by category and card.

License

SmartCard is source-available under the PolyForm Strict License 1.0.0.

Allowed?

Read the code and run it for personal, study, research or other noncommercial use

✅ Yes

Use it in a commercial product or service, or inside a business

❌ No

Modify it, fork it into a new work, or redistribute it

❌ No

For commercial licensing or any use not covered above, open an issue on this repository to contact the author.

Copyright © 2026 Shubham Kumar Sahoo. All rights not expressly granted are reserved.

Available Tools

15 tools
add_cardA

Add a credit card to the wallet, then call add_earn_rate for each category or merchant where it earns more than its base rate.

Wrong terms silently skew every later recommendation, so saving needs the user's
agreement: call once without `confirmed` to get a preview, show it to the user
(including anything found with search_card_terms and their statement day), and
call again with confirmed=true only after they agree.

Inputs: name (required), issuer (required), base_rate (required), reward_kind (required), +7 more. Returns: object

add_earn_rateA

Add an accelerated reward rate to a card for a category, a merchant, or both. When several rates match a purchase, the most specific one wins (merchant beats category). Only add rates the user has confirmed.

Inputs: card (required), rate (required), label, channel, +3 more. Returns: object

adjust_rewardsA

Record points or cashback that did not come from a purchase.

Inputs: card (required), note (required), units (required), on, +1 more. Returns: object

card_detailsB
Read-only

Everything about one card: base rate, accelerated earn rates, how much of each monthly cap is used in the current statement cycle, and its reward balance.

Inputs: card (required). Returns: object

delete_purchaseA
Destructive

Delete a purchase logged by mistake. Ask the user first.

Inputs: purchase_id (required). Returns: object

list_cardsA
Read-only

List every card in the wallet with its base earning rate.

Inputs: no named parameters. Returns: object

list_purchasesB
Read-only

Show purchases, newest first, optionally filtered.

Inputs: end, card, limit, start, +2 more. Returns: object

log_purchaseB

Record a purchase made on a card and calculate the rewards it earned. Also says whether another card in the wallet would have earned more.

Inputs: card (required), amount (required), merchant (required), note, +3 more. Returns: object

recommend_cardA
Read-only

Rank every card in the wallet by the rupee value it would give back on this purchase, taking monthly caps already used into account.

Inputs: amount (required), merchant (required), channel, category. Returns: object

remove_cardA
Destructive

Delete a card and all its earn rates, purchases and point adjustments. Call once without confirm to see what would be deleted, then ask the user.

Inputs: card (required), confirm. Returns: object

remove_earn_rateA
Destructive

Delete one earn rate (ids are shown by card_details).

Inputs: rate_id (required). Returns: object

rewards_balanceB
Read-only

Reward balance per card: earned from purchases, plus or minus manual adjustments, and what the balance is worth in rupees.

Inputs: card. Returns: object

search_card_termsA
Read-only

Search the web for a card's published reward terms. Results are raw snippets: summarise them for the user and confirm before saving anything.

Inputs: card_name (required), topic, max_results. Returns: object

spending_reportA
Read-only

Spending and rewards by category and by card. With no dates, covers the current calendar month.

Inputs: end, start. Returns: object

update_cardB

Change details of an existing card. Only the fields you pass are changed.

Inputs: card (required), name, notes, issuer, +6 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 15 tools

    Disambiguation4/5

    Each tool targets a distinct resource+action (cards, earn rates, purchases, rewards, reports), and the confirmation-flow tools (add_card, remove_card) are explicitly documented. Minor overlap exists between card_details (which includes reward balance) and rewards_balance, but the descriptions make the intended split clear enough.

    Naming Consistency4/5

    Mostly a clean verb_noun snake_case pattern (list_cards, add_card, remove_card, add_earn_rate, log_purchase, delete_purchase, adjust_rewards). A few outliers are noun-only (card_details, rewards_balance, spending_report), which breaks the pattern slightly but remains readable and predictable.

    Tool Count5/5

    15 tools is within the well-scoped range and each one maps to a concrete operation in a wallet/rewards domain. Nothing appears redundant or padded.

    Completeness4/5

    Cards, earn rates, purchases, rewards, and reporting all have lifecycle coverage, including a search tool for reward terms and preview/confirm flows for destructive operations. Gaps are minor: there is no update_purchase or update_earn_rate (users must delete and re-add), which agents can work around.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides tools to fetch and analyze credit card data with filtering options for banks, categories, and user personas. It also offers access to educational guides to assist in making informed financial recommendations.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables agents to recommend the best credit card for a given store or category, look up merchant coding, search cards, and inspect rotating bonus calendars using verified reward data.
      5
      906 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to choose the best card for a purchase with reasons, identify merchants, inspect wallet caps and bonus progress, compare public welcome offers, and record purchases against caps and bonuses.
      651 npm
      1
      MIT