💵 Financial Gateway MCP Server

Give your AI assistant a built-in financial calculator. This Model Context Protocol (MCP) server hands Claude, Cursor, or any MCP client three precise money tools — client estimates, loan amortization, and currency conversion — so it can crunch real numbers instead of guessing them.

Every result is pure deterministic math: the same input always gives the same answer, computed entirely from the values you pass in. No API keys. No outbound calls. No made-up data.

---

✨ Why use it

LLMs are notoriously unreliable at arithmetic — they'll happily "estimate" a loan payment and be off by hundreds of dollars. This Actor gives your AI a tool that returns exact, auditable, repeatable figures every time, with the formula and inputs visible in the output.

Perfect for:

• 🧾 AI agents that draft quotes & estimates for clients (line items → subtotal → discount → tax → total)
• 🏦 Assistants that answer "what would the monthly payment be?" with the real amortization formula
• 💱 Workflows that need deterministic currency math from a rate you control (no surprise live-rate drift)
• 🤖 Any MCP client (Claude Desktop, Cursor, MCP Inspector) that should calculate, not hallucinate

---

🛠️ The three tools

Tool	What it does
calculate_estimate	Builds a line-item estimate — per-line totals, subtotal, optional discount, optional tax, and grand total.
amortize_loan	Fixed-rate loan summary — monthly payment, total paid, and total interest (standard amortization formula).
currency_convert	Converts an amount using an FX rate you supply (no live-rate lookups, so results stay reproducible).

Speaks MCP over JSON-RPC 2.0 — supports initialize, tools/list, and tools/call.

---

🚀 Quick start

On Apify — paste a single JSON-RPC request into the query input and run. The Actor executes it, saves the response as OUTPUT, logs it to the dataset, and exits. (Leave query empty to get the tool catalog back.)

Example — amortize a $25,000 loan at 6.5% over 60 months:

{
  "query": "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"amortize_loan\",\"arguments\":{\"principal\":25000,\"annualRatePct\":6.5,\"termMonths\":60}}}"
}

Locally as an MCP server — run node src/main.js with no input. It reads newline-delimited JSON-RPC on stdin and replies on stdout — the standard transport for Claude Desktop and the MCP Inspector.

---

🔌 Connect it to your MCP client

Run it locally and add it to Claude Desktop (claude_desktop_config.json) or Cursor:

{
  "mcpServers": {
    "financial-gateway": {
      "command": "node",
      "args": ["/absolute/path/to/financial-gateway-mcp/src/main.js"]
    }
  }
}

Restart the client and the three tools (calculate_estimate, amortize_loan, currency_convert) appear automatically. You can also point the MCP Inspector at the same command to try the tools interactively.

---

📥 Tool arguments

calculate_estimate

Argument	Type	Required	Notes
items	array of { description?, quantity, unitPrice }	Yes	Non-empty; quantity and unitPrice must be numbers.
discountPct	number	No	0–100, applied to the subtotal. Default 0.
taxPct	number	No	≥ 0, applied after the discount. Default 0.
client	string	No	Echoed back on the result.
currency	string	No	Label only; defaults to "USD".

amortize_loan

Argument	Type	Required	Notes
principal	number	Yes	> 0.
annualRatePct	number	Yes	≥ 0 (a 0% rate becomes straight-line repayment).
termMonths	integer	Yes	Integer > 0.

currency_convert

Argument	Type	Required	Notes
amount	number	Yes
rate	number	Yes	FX multiplier > 0 — you supply it, it is not fetched.
from / to	string	No	Labels only.

---

📤 What you get back

The JSON-RPC response is saved as OUTPUT, and every tool call is appended to the dataset with its arguments, result, and timestamp.

Example — amortize_loan for $350,000 @ 5.5% over 180 months:

{
  "principal": 350000,
  "annualRatePct": 5.5,
  "termMonths": 180,
  "monthlyPayment": 2859.79,
  "totalPaid": 514762.58,
  "totalInterest": 164762.58
}

Example — calculate_estimate for 8 units @ $175 with 7% tax:

{
  "client": "Acme LLC", "currency": "USD",
  "lineItems": [{ "description": "Consulting", "quantity": 8, "unitPrice": 175, "lineTotal": 1400 }],
  "subtotal": 1400, "discountPct": 0, "discountAmount": 0,
  "taxPct": 7, "taxAmount": 98, "total": 1498
}

---

🔒 No setup, no surprises

• Zero configuration. No API keys, OAuth, or credentials. The Actor makes no outbound network calls — your numbers never leave the run.
• Deterministic & auditable. Same input → same output, every time. The result echoes the inputs so the math is checkable.
• Honest by design. It does not connect to QuickBooks, Stripe, Xero, banks, or any FX feed, and it does not store or retrieve real invoices or accounts. It's a stateless calculator — nothing is faked.

⚠️ Limitations

• No live or external data. The Actor makes zero outbound network calls. currency_convert never fetches live FX — you must supply the rate. It does not connect to banks, QuickBooks, Stripe, Xero, or any FX feed, and it neither stores nor retrieves real invoices or accounts.
• Narrow calculation scope. amortize_loan is the standard fixed-rate formula with monthly compounding only — no fees, escrow, PMI, variable rates, or extra payments. calculate_estimate applies exactly one flat discount and one flat tax rate. All figures are rounded to 2 decimals.
• One request per platform run. In Apify one-shot mode the query input executes exactly one JSON-RPC request and then the run exits. For interactive, multi-call MCP sessions, run it locally over stdio and connect an MCP client.
• Requires an MCP client for live use. On the Apify platform there is no persistent stdio MCP endpoint or Standby server — the platform path is one-shot query execution (or it returns the tools/list catalog when query is empty). Live, multi-turn tool use happens through a local MCP client over stdio.
• Best-effort persistence. Dataset writes are best-effort: if a dataset push fails, the tool call still returns its result but that record is not saved to the dataset.
• Not advice. Results are arithmetic only — not financial, tax, accounting, or investment advice. Verify figures before relying on them in any financial or regulatory context.
• Error handling. Bad arguments return a clean JSON-RPC error (-32602), unknown tools return -32601, and a malformed query fails with an explanatory message — never a crash.

❓ FAQ

Does it connect to my bank, QuickBooks, Stripe, or a live FX feed? No. It makes zero outbound network calls. Every result is computed purely from the inputs you pass in — including the FX rate, which you supply. Nothing is fetched or stored.

Do I need an API key or any credentials? No. There's nothing to configure — paste a request and run, or wire it into your MCP client.

Why use a tool instead of just asking the LLM to do the math? LLMs frequently make arithmetic errors on multi-step money math (amortization, compounded totals, tax-on-discounted-subtotal). This tool returns exact, repeatable, auditable figures with the inputs echoed back so the result is checkable.

Which MCP clients work? Any MCP client that speaks the standard stdio JSON-RPC transport, such as Claude Desktop, Cursor, or the MCP Inspector. See "Connect it to your MCP client" above for the config.

Is the currency conversion using real exchange rates? Only the rate you provide. This keeps results reproducible and free of surprise live-rate drift. If you need live rates, fetch them upstream and pass the value in.

Is this financial, accounting, or tax advice? No. It's an arithmetic calculator. Always verify figures before using them in any financial, accounting, or regulatory context.