SmartCard
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SmartCard which card should I use for ₹2,400 on Swiggy?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
Interface (
server.py): 15 tools, 1 resource and 1 prompt with validated inputs and tool annotations.Service (
wallet.py): every business operation, usable and testable without MCP.Engines (
rewards.py,categories.py): pure reward maths and category intelligence, with no I/O.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 |
| MCP tools, resource and prompt. Thin: validates input, formats output |
| All operations (cards, rates, purchases, balances, reports) |
| Pure reward calculation: rate matching, blocks, caps, billing cycles |
| SQLite schema and row mapping |
| Spending categories, synonyms and merchant hints |
|
|
| 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 |
|
|
|
|
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 outData 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-mcpOn 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 smartcardClaude 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 |
| Cards in the wallet with base rates |
| One card: earn rates, cap usage this cycle, balance |
| Manage cards ( |
| Accelerated rates per category or merchant |
| Best card for a purchase, with a full ranking |
| Purchase history |
| Balances, bonuses and redemptions |
| Spend and return by category and card |
| 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 callsadd_cardandadd_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 toolsadd_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_detailsBRead-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_purchaseADestructive
Delete a purchase logged by mistake. Ask the user first.
Inputs: purchase_id (required). Returns: object
list_cardsARead-only
List every card in the wallet with its base earning rate.
Inputs: no named parameters. Returns: object
list_purchasesBRead-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_cardARead-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_cardADestructive
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_rateADestructive
Delete one earn rate (ids are shown by card_details).
Inputs: rate_id (required). Returns: object
rewards_balanceBRead-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_termsARead-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_reportARead-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
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
AI credit card advisor - search cards, compare portfolios, and optimize rewards
Ask Claude or ChatGPT about your own credit cards: best card to use, utilization, missed rewards.
Search, compare and estimate rewards across US credit cards. Verified fees, APRs and bonuses.
Which of your credit cards to use at any store, from verified bank data. No bank login.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides 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.-
- FlicenseNot gradedqualityDmaintenanceEnables searching and comparing live credit card merchant offers (cash back, points, statement credits) across Amex, Chase, Citi, PayPal, Rakuten, and Capital One from any AI agent.-
- AlicenseAqualityCmaintenanceEnables 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.5906 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables 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 npm1MIT