therealcost-mcp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. therealcost_mcp-0.1.0/.gitignore +15 -0
  2. therealcost_mcp-0.1.0/LICENSE +21 -0
  3. therealcost_mcp-0.1.0/LISTINGS.md +18 -0
  4. therealcost_mcp-0.1.0/PKG-INFO +315 -0
  5. therealcost_mcp-0.1.0/README.md +266 -0
  6. therealcost_mcp-0.1.0/REGISTRY_SUBMISSION.md +94 -0
  7. therealcost_mcp-0.1.0/glama.json +4 -0
  8. therealcost_mcp-0.1.0/pyproject.toml +43 -0
  9. therealcost_mcp-0.1.0/server.json +22 -0
  10. therealcost_mcp-0.1.0/tests/__init__.py +0 -0
  11. therealcost_mcp-0.1.0/tests/test_calc.py +204 -0
  12. therealcost_mcp-0.1.0/tests/test_server.py +230 -0
  13. therealcost_mcp-0.1.0/therealcost_mcp/__init__.py +1 -0
  14. therealcost_mcp-0.1.0/therealcost_mcp/calc.py +210 -0
  15. therealcost_mcp-0.1.0/therealcost_mcp/schemas.py +87 -0
  16. therealcost_mcp-0.1.0/therealcost_mcp/server.py +610 -0
therealcost_mcp-0.1.0/.gitignore ADDED
@@ -0,0 +1,15 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.so
4
+ build/
5
+ dist/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .coverage
9
+ .venv/
10
+ venv/
11
+ .env
12
+ .env.*
13
+ .vscode/
14
+ .idea/
15
+ .DS_Store
therealcost_mcp-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ryan Hammer (NoBanks Nearby)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
therealcost_mcp-0.1.0/LISTINGS.md ADDED
@@ -0,0 +1,18 @@
1
+ # therealcost-mcp listings log
2
+
3
+ Description used everywhere:
4
+ Free money calculators for AI agents from The Real Cost by NoBanks Nearby: credit card payoff, debt consolidation, loan cost by term, crypto trade cost and emergency fund, with the math shown and links to pre-filled calculators. Education only, not financial advice.
5
+
6
+ (The official registry's server.json description field is capped at 100 characters, so server.json keeps the short version.)
7
+
8
+ | Date | Listing | URL | Status | Notes |
9
+ |---|---|---|---|---|
10
+ | 2026-10-01 | PyPI | https://pypi.org/project/therealcost-mcp/ | BLOCKED | No PyPI token on this Mac (no ~/.pypirc, no PYPI/TWINE vars in ~/.hermes/.env). Name is free (404). Build 0.1.0 at commit 3c84228 passes twine check, 53 tests pass, wheel installs in a fresh venv and lists all 6 tools over stdio. Ryan must create the account/token, then: `TWINE_USERNAME=__token__ TWINE_PASSWORD=<token> python3.11 -m twine upload dist/*` |
11
+ | 2026-10-01 | Official MCP Registry | https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.NoBanks/therealcost-mcp | BLOCKED (waits on PyPI) | mcp-publisher 1.8.1 installed via brew; `mcp-publisher validate` says server.json is valid; README has `mcp-name: io.github.NoBanks/therealcost-mcp`. Registry checks the PyPI package, so publish after PyPI: `mcp-publisher login github` then `mcp-publisher publish`. PulseMCP and Smithery read from this registry. |
12
+ | 2026-10-01 | Glama | https://glama.ai/mcp/servers/NoBanks/therealcost-mcp | LIVE | Auto-indexed from GitHub (Finance, Education & Learning), score badge serving. "Claim" needs a Glama login (optional). |
13
+ | 2026-10-01 | awesome-mcp-servers (punkpeye) | https://github.com/punkpeye/awesome-mcp-servers/pull/15493 | PENDING REVIEW | One-line entry in Finance & Fintech, alphabetical, with Glama badge, per CONTRIBUTING.md. |
14
+ | 2026-10-01 | mcp.so | https://github.com/chatmcp/mcpso/issues/1#issuecomment-5938727954 | PENDING REVIEW | The mcp.so/submit web form now only offers the paid $39 path (not used). Submitted through the free route the maintainers run: issue #1 "Submit Your MCP Servers here". |
15
+ | 2026-10-01 | mcpservers.org (wong2 awesome-mcp-servers site) | https://mcpservers.org/submit | APPROVED (2026-10-02, per approval email to nobanksnearby@gmail.com) | Free plan, category Finance. Approved within a day of submission. wong2's GitHub list takes no PRs and points here. |
16
+ | 2026-10-01 | Smithery | https://smithery.ai/new | SKIPPED for now | Requires login; Smithery pulls from the Official MCP Registry, so check after the registry publish before submitting by hand. |
17
+ | 2026-10-01 | PulseMCP | n/a | COVERED BY REGISTRY | No direct submissions; ingests the Official MCP Registry. |
18
+ | 2026-10-01 | appcypher/awesome-mcp-servers | https://github.com/appcypher/awesome-mcp-servers | SKIPPED | Repository is archived. |
therealcost_mcp-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,315 @@
1
+ Metadata-Version: 2.5
2
+ Name: therealcost-mcp
3
+ Version: 0.1.0
4
+ Summary: Free money calculators for AI agents, from The Real Cost (therealcost.nohumannearby.com): credit card payoff, debt consolidation, loan cost by term, crypto trading fees and emergency fund, each with the formula in words and a pre-filled calculator link. Education only.
5
+ Project-URL: Homepage, https://therealcost.nohumannearby.com
6
+ Project-URL: Calculators, https://therealcost.nohumannearby.com/calculators/
7
+ Project-URL: Guides, https://therealcost.nohumannearby.com/books/
8
+ Project-URL: Repository, https://github.com/NoBanks/therealcost-mcp
9
+ Author-email: The Real Cost by NoBanks Nearby <nobanksnearby@gmail.com>
10
+ License: MIT License
11
+
12
+ Copyright (c) 2026 Ryan Hammer (NoBanks Nearby)
13
+
14
+ Permission is hereby granted, free of charge, to any person obtaining a copy
15
+ of this software and associated documentation files (the "Software"), to deal
16
+ in the Software without restriction, including without limitation the rights
17
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
18
+ copies of the Software, and to permit persons to whom the Software is
19
+ furnished to do so, subject to the following conditions:
20
+
21
+ The above copyright notice and this permission notice shall be included in all
22
+ copies or substantial portions of the Software.
23
+
24
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
25
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
26
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
27
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
28
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
29
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
30
+ SOFTWARE.
31
+ License-File: LICENSE
32
+ Keywords: ai-agents,calculator,credit-card,crypto-fees,debt-consolidation,emergency-fund,financial-education,loan,mcp,model-context-protocol,personal-finance
33
+ Classifier: Development Status :: 4 - Beta
34
+ Classifier: Intended Audience :: Developers
35
+ Classifier: Intended Audience :: End Users/Desktop
36
+ Classifier: License :: OSI Approved :: MIT License
37
+ Classifier: Programming Language :: Python :: 3
38
+ Classifier: Programming Language :: Python :: 3.10
39
+ Classifier: Programming Language :: Python :: 3.11
40
+ Classifier: Programming Language :: Python :: 3.12
41
+ Classifier: Topic :: Office/Business :: Financial
42
+ Requires-Python: >=3.10
43
+ Requires-Dist: mcp<2,>=1.20.0
44
+ Requires-Dist: pydantic>=2.0.0
45
+ Provides-Extra: dev
46
+ Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
47
+ Requires-Dist: pytest>=7.0.0; extra == 'dev'
48
+ Description-Content-Type: text/markdown
49
+
50
+ # therealcost-mcp
51
+
52
+ **Free money calculators for AI agents, from [The Real Cost](https://therealcost.nohumannearby.com).**
53
+
54
+ The Real Cost by NoBanks Nearby is a free set of US money calculators with the math shown:
55
+ credit card payoff, debt consolidation, loan cost by term, crypto trading fees and emergency fund.
56
+ This MCP server lets Claude and other AI assistants run those exact calculators and hand the user
57
+ a link to the same calculator on the site, already filled in with their numbers, so they can check
58
+ the math and keep adjusting it.
59
+
60
+ - Site: https://therealcost.nohumannearby.com
61
+ - All calculators: https://therealcost.nohumannearby.com/calculators/
62
+ - Guides: https://therealcost.nohumannearby.com/books/
63
+
64
+ **Education only. Not financial advice.** Results are estimates from the numbers entered.
65
+
66
+ <!-- mcp-name: io.github.NoBanks/therealcost-mcp -->
67
+
68
+ ## What every result includes
69
+
70
+ Each calculator tool returns JSON with:
71
+
72
+ | Key | What it is |
73
+ | --- | --- |
74
+ | `result` | The numbers (months, total interest, payments, costs) |
75
+ | `summary` | The result in one plain-English paragraph |
76
+ | `formula` | The formula in words, so the user can see how the number was made |
77
+ | `calculator_url` | The matching page on therealcost.nohumannearby.com, pre-filled with the inputs |
78
+ | `warnings` | Present when a plan never pays off or never reaches the goal |
79
+ | `go_deeper` | The matching guide and chapters, with the guides link |
80
+ | `source` | "The Real Cost by NoBanks Nearby, https://therealcost.nohumannearby.com" |
81
+ | `disclaimer` | "Education only. Not financial advice." |
82
+
83
+ The math is a line-for-line port of the site's own calculator code, and the test suite reuses the
84
+ site's hand-checked cases, so a number from this server matches the number on the site.
85
+ No network calls, no API keys, no tracking.
86
+
87
+ ## The guides
88
+
89
+ The Real Cost also publishes ten plain-English guides that go deeper than any one calculation,
90
+ with every number worked out step by step (PDF and EPUB):
91
+
92
+ | Guide | Pages | Goes with |
93
+ | --- | --- | --- |
94
+ | The Real Cost of Credit Card Debt | 112 | credit card payoff, debt consolidation |
95
+ | The Real Cost of Loans and Big Purchases | 110 | loan cost by term, debt consolidation |
96
+ | The Real Cost of Everyday Spending | 123 | emergency fund |
97
+ | The Real Cost of Crypto Fees and Taxes | 110 | crypto trade cost |
98
+ | The Real Cost of Credit Reports and Scores | 115 | loan cost by term |
99
+ | The Real Cost of Paychecks and Taxes | 109 | |
100
+ | The Real Cost of Retirement Accounts | 117 | |
101
+ | The Real Cost of Student Loans | 115 | |
102
+ | The Real Cost of Renting and Buying a Home | 125 | loan cost by term |
103
+ | The Real Cost of Scams and Fraud | 103 | |
104
+
105
+ $4.99 each at https://therealcost.nohumannearby.com/books/ . All ten come together as the complete set
106
+ for $24.95 (10 for the price of 5). Guides 1-3 also come as a starter pack for $9.98 (3 for the price
107
+ of 2); the starter pack does not include guides 4-10.
108
+
109
+ Free sample chapters (Chapter 1 of each guide, PDF):
110
+
111
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-credit-card-debt-chapter-1.pdf
112
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-loans-and-big-purchases-chapter-1.pdf
113
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-everyday-spending-chapter-1.pdf
114
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-crypto-fees-and-taxes-chapter-1.pdf
115
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-credit-reports-and-scores-chapter-1.pdf
116
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-paychecks-and-taxes-chapter-1.pdf
117
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-retirement-accounts-chapter-1.pdf
118
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-student-loans-chapter-1.pdf
119
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-renting-and-buying-a-home-chapter-1.pdf
120
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-scams-and-fraud-chapter-1.pdf
121
+
122
+ The server tells connected agents about the guides in its instructions, and each calculator result
123
+ names the matching guide, its relevant chapters and its free sample chapter in a calm one-line `go_deeper` block. The calculators are free and complete
124
+ on their own.
125
+
126
+ ## Install
127
+
128
+ Requires Python 3.10+. The easiest runner is [uv](https://docs.astral.sh/uv/).
129
+
130
+ ### Claude Code
131
+
132
+ ```bash
133
+ claude mcp add therealcost -- uvx --from git+https://github.com/NoBanks/therealcost-mcp therealcost-mcp
134
+ ```
135
+
136
+ ### Claude Desktop
137
+
138
+ Add this to `claude_desktop_config.json` (Settings, Developer, Edit Config), then restart Claude Desktop:
139
+
140
+ ```json
141
+ {
142
+ "mcpServers": {
143
+ "therealcost": {
144
+ "command": "uvx",
145
+ "args": ["--from", "git+https://github.com/NoBanks/therealcost-mcp", "therealcost-mcp"]
146
+ }
147
+ }
148
+ }
149
+ ```
150
+
151
+ ### From a local clone
152
+
153
+ ```bash
154
+ git clone https://github.com/NoBanks/therealcost-mcp
155
+ cd therealcost-mcp
156
+ pip install -e .
157
+ therealcost-mcp # speaks MCP over stdio
158
+ ```
159
+
160
+ Then point your client at the `therealcost-mcp` command (Claude Code: `claude mcp add therealcost -- therealcost-mcp`).
161
+
162
+ ## Tools
163
+
164
+ ### `credit_card_payoff`
165
+
166
+ Months and total interest to clear a card balance paying only the minimum, versus a fixed monthly payment.
167
+
168
+ | Input | Type | Default | Notes |
169
+ | --- | --- | --- | --- |
170
+ | `balance` | number | required | dollars |
171
+ | `apr` | number | required | percent, 24 means 24% |
172
+ | `payment` | number | none | fixed monthly payment to compare |
173
+ | `min_pct` | number | 1 | minimum = this % of the balance |
174
+ | `min_floor` | number | 25 | dollar floor on the minimum |
175
+ | `min_plus_interest` | boolean | true | minimum also includes that month's interest |
176
+
177
+ ```json
178
+ {"name": "credit_card_payoff", "arguments": {"balance": 5000, "apr": 24, "payment": 200}}
179
+ ```
180
+
181
+ Result (abridged): minimum only 234 months and $8,886.95 interest; $200 a month 36 months and
182
+ $2,000.56 interest; link
183
+ `https://therealcost.nohumannearby.com/calculators/credit-card-payoff/?balance=5000&apr=24&minPct=1&minFloor=25&plusInterest=1&fixedPayment=200`
184
+
185
+ ### `debt_consolidation`
186
+
187
+ Current debts versus one consolidation loan, including the origination fee (taken out of the loan, so
188
+ the loan is sized up to total / (1 - fee%)).
189
+
190
+ | Input | Type | Default | Notes |
191
+ | --- | --- | --- | --- |
192
+ | `debts` | array | required | 1 to 10 items of `{balance, apr, payment, name?}` |
193
+ | `loan_apr` | number | required | percent |
194
+ | `loan_term_months` | integer | required | 1 to 600 |
195
+ | `origination_fee_pct` | number | 0 | percent |
196
+
197
+ ```json
198
+ {"name": "debt_consolidation", "arguments": {
199
+ "debts": [{"balance": 6000, "apr": 24.99, "payment": 200},
200
+ {"balance": 3000, "apr": 27.99, "payment": 110},
201
+ {"balance": 2500, "apr": 19.99, "payment": 90}],
202
+ "loan_apr": 13, "loan_term_months": 48, "origination_fee_pct": 5}}
203
+ ```
204
+
205
+ ### `loan_cost_by_term`
206
+
207
+ Monthly payment, total interest and total paid for one loan over several terms.
208
+
209
+ | Input | Type | Default | Notes |
210
+ | --- | --- | --- | --- |
211
+ | `principal` | number | required | dollars |
212
+ | `apr` | number | required | percent |
213
+ | `terms` | integer array | [36, 48, 60, 72, 84] | months; the first two pre-fill the site |
214
+
215
+ ```json
216
+ {"name": "loan_cost_by_term", "arguments": {"principal": 25000, "apr": 8, "terms": [36, 60]}}
217
+ ```
218
+
219
+ Result (abridged): 36 months $783.41 a month; 60 months $506.91 a month.
220
+
221
+ ### `crypto_trade_cost`
222
+
223
+ Trading fee, spread and network fees on a buy and a later sale at the same price, the price rise
224
+ needed to break even, and the yearly cost of recurring buys.
225
+
226
+ | Input | Type | Default | Notes |
227
+ | --- | --- | --- | --- |
228
+ | `amount` | number | required | dollars bought |
229
+ | `fee_pct` | number | required | trading fee per trade, percent |
230
+ | `spread_pct` | number | required | spread per trade, percent |
231
+ | `network_fee_buy` | number | 0 | flat dollars after the buy |
232
+ | `network_fee_sell` | number | 0 | flat dollars to move coins back to sell |
233
+ | `weekly_buy` | number | none | recurring buy amount; adds the yearly cost |
234
+ | `buys_per_year` | integer | 52 | 52 weekly, 26 biweekly, 12 monthly |
235
+ | `flat_fee_per_buy` | number | 0 | flat fee some platforms add on small buys |
236
+
237
+ ```json
238
+ {"name": "crypto_trade_cost", "arguments": {"amount": 1000, "fee_pct": 0.6, "spread_pct": 0.5,
239
+ "network_fee_buy": 2.5, "network_fee_sell": 2.5, "weekly_buy": 25, "flat_fee_per_buy": 0.99}}
240
+ ```
241
+
242
+ ### `emergency_fund`
243
+
244
+ Goal = monthly expenses x months to cover. Months to reach it, and the monthly amount needed to reach
245
+ it by a target.
246
+
247
+ | Input | Type | Default | Notes |
248
+ | --- | --- | --- | --- |
249
+ | `monthly_expenses` | number | required | must-pay expenses per month |
250
+ | `months_covered` | integer | required | 1 to 60 |
251
+ | `saved` | number | 0 | already saved |
252
+ | `monthly_add` | number | 0 | added each month |
253
+ | `apy` | number | 0 | savings APY, percent |
254
+ | `target_months` | integer | 12 | reach the goal in this many months |
255
+ | `target_date` | string | none | `YYYY-MM` or `YYYY-MM-DD`, instead of `target_months` |
256
+
257
+ ```json
258
+ {"name": "emergency_fund", "arguments": {"monthly_expenses": 2500, "months_covered": 3,
259
+ "saved": 500, "monthly_add": 300, "target_date": "2027-10"}}
260
+ ```
261
+
262
+ Result (abridged): goal $7,500.00; 24 months to reach it at $300 a month; $583.33 a month reaches it in 12 months.
263
+
264
+ ### `list_guides`
265
+
266
+ No inputs. Returns the ten guides (title, subtitle, pages, what each covers, price), the complete
267
+ set ($24.95 for all ten, 10 for the price of 5), the starter pack price (guides 1-3 only), and the
268
+ guides link.
269
+
270
+ ```json
271
+ {"name": "list_guides", "arguments": {}}
272
+ ```
273
+
274
+ ### Errors
275
+
276
+ Bad input never crashes the server. It returns:
277
+
278
+ ```json
279
+ {"error": {"type": "validation_error", "message": "Invalid input for credit_card_payoff.",
280
+ "details": [{"field": "apr", "message": "Field required"}]},
281
+ "disclaimer": "Education only. Not financial advice."}
282
+ ```
283
+
284
+ ## Calculator link parameters (for the site)
285
+
286
+ `calculator_url` uses the site's own form field ids as query parameters, so the site can pre-fill
287
+ each form by reading `?name=value` into the field with that id. Numbers are plain (`5000`, `24.99`);
288
+ booleans are `1` or `0`.
289
+
290
+ | Calculator page | Parameters |
291
+ | --- | --- |
292
+ | `/calculators/credit-card-payoff/` | `balance`, `apr`, `minPct`, `minFloor`, `plusInterest`, `fixedPayment` |
293
+ | `/calculators/debt-consolidation/` | `d1b`, `d1r`, `d1p`, `d2b`, `d2r`, `d2p`, `d3b`, `d3r`, `d3p` (balance, APR, payment per debt), `loanApr`, `loanMonths`, `feePct` |
294
+ | `/calculators/loan-term/` | `amount`, `apr`, `termA`, `termB` |
295
+ | `/calculators/crypto-trade-cost/` | `amount`, `feePct`, `spreadPct`, `networkBuy`, `networkSell`, `weekly`, `freq`, `flatFee` |
296
+ | `/calculators/emergency-fund/` | `expenses`, `monthsCover`, `saved`, `monthly`, `apy`, `target` |
297
+
298
+ Notes: unused debt rows are sent as `dNb=0` so the form's example rows are not counted. With more
299
+ than 3 debts the link opens the plain page (the form has 3 rows) and the result says so. Some site
300
+ fields are dropdowns (loan terms, months to cover, target, frequency); a value outside the dropdown's
301
+ options needs the site to add that option or fall back to its default.
302
+
303
+ ## Development
304
+
305
+ ```bash
306
+ pip install -e ".[dev]"
307
+ pytest
308
+ ```
309
+
310
+ `tests/test_calc.py` is a port of the site's `site/tests/calc-math.test.js` (same hand-checked cases
311
+ and the same cross-checks), and `tests/test_server.py` awaits `list_tools` and `call_tool` directly.
312
+
313
+ ## License
314
+
315
+ MIT. The Real Cost by NoBanks Nearby.
therealcost_mcp-0.1.0/README.md ADDED
@@ -0,0 +1,266 @@
1
+ # therealcost-mcp
2
+
3
+ **Free money calculators for AI agents, from [The Real Cost](https://therealcost.nohumannearby.com).**
4
+
5
+ The Real Cost by NoBanks Nearby is a free set of US money calculators with the math shown:
6
+ credit card payoff, debt consolidation, loan cost by term, crypto trading fees and emergency fund.
7
+ This MCP server lets Claude and other AI assistants run those exact calculators and hand the user
8
+ a link to the same calculator on the site, already filled in with their numbers, so they can check
9
+ the math and keep adjusting it.
10
+
11
+ - Site: https://therealcost.nohumannearby.com
12
+ - All calculators: https://therealcost.nohumannearby.com/calculators/
13
+ - Guides: https://therealcost.nohumannearby.com/books/
14
+
15
+ **Education only. Not financial advice.** Results are estimates from the numbers entered.
16
+
17
+ <!-- mcp-name: io.github.NoBanks/therealcost-mcp -->
18
+
19
+ ## What every result includes
20
+
21
+ Each calculator tool returns JSON with:
22
+
23
+ | Key | What it is |
24
+ | --- | --- |
25
+ | `result` | The numbers (months, total interest, payments, costs) |
26
+ | `summary` | The result in one plain-English paragraph |
27
+ | `formula` | The formula in words, so the user can see how the number was made |
28
+ | `calculator_url` | The matching page on therealcost.nohumannearby.com, pre-filled with the inputs |
29
+ | `warnings` | Present when a plan never pays off or never reaches the goal |
30
+ | `go_deeper` | The matching guide and chapters, with the guides link |
31
+ | `source` | "The Real Cost by NoBanks Nearby, https://therealcost.nohumannearby.com" |
32
+ | `disclaimer` | "Education only. Not financial advice." |
33
+
34
+ The math is a line-for-line port of the site's own calculator code, and the test suite reuses the
35
+ site's hand-checked cases, so a number from this server matches the number on the site.
36
+ No network calls, no API keys, no tracking.
37
+
38
+ ## The guides
39
+
40
+ The Real Cost also publishes ten plain-English guides that go deeper than any one calculation,
41
+ with every number worked out step by step (PDF and EPUB):
42
+
43
+ | Guide | Pages | Goes with |
44
+ | --- | --- | --- |
45
+ | The Real Cost of Credit Card Debt | 112 | credit card payoff, debt consolidation |
46
+ | The Real Cost of Loans and Big Purchases | 110 | loan cost by term, debt consolidation |
47
+ | The Real Cost of Everyday Spending | 123 | emergency fund |
48
+ | The Real Cost of Crypto Fees and Taxes | 110 | crypto trade cost |
49
+ | The Real Cost of Credit Reports and Scores | 115 | loan cost by term |
50
+ | The Real Cost of Paychecks and Taxes | 109 | |
51
+ | The Real Cost of Retirement Accounts | 117 | |
52
+ | The Real Cost of Student Loans | 115 | |
53
+ | The Real Cost of Renting and Buying a Home | 125 | loan cost by term |
54
+ | The Real Cost of Scams and Fraud | 103 | |
55
+
56
+ $4.99 each at https://therealcost.nohumannearby.com/books/ . All ten come together as the complete set
57
+ for $24.95 (10 for the price of 5). Guides 1-3 also come as a starter pack for $9.98 (3 for the price
58
+ of 2); the starter pack does not include guides 4-10.
59
+
60
+ Free sample chapters (Chapter 1 of each guide, PDF):
61
+
62
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-credit-card-debt-chapter-1.pdf
63
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-loans-and-big-purchases-chapter-1.pdf
64
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-everyday-spending-chapter-1.pdf
65
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-crypto-fees-and-taxes-chapter-1.pdf
66
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-credit-reports-and-scores-chapter-1.pdf
67
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-paychecks-and-taxes-chapter-1.pdf
68
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-retirement-accounts-chapter-1.pdf
69
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-student-loans-chapter-1.pdf
70
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-renting-and-buying-a-home-chapter-1.pdf
71
+ - https://therealcost.nohumannearby.com/samples/the-real-cost-of-scams-and-fraud-chapter-1.pdf
72
+
73
+ The server tells connected agents about the guides in its instructions, and each calculator result
74
+ names the matching guide, its relevant chapters and its free sample chapter in a calm one-line `go_deeper` block. The calculators are free and complete
75
+ on their own.
76
+
77
+ ## Install
78
+
79
+ Requires Python 3.10+. The easiest runner is [uv](https://docs.astral.sh/uv/).
80
+
81
+ ### Claude Code
82
+
83
+ ```bash
84
+ claude mcp add therealcost -- uvx --from git+https://github.com/NoBanks/therealcost-mcp therealcost-mcp
85
+ ```
86
+
87
+ ### Claude Desktop
88
+
89
+ Add this to `claude_desktop_config.json` (Settings, Developer, Edit Config), then restart Claude Desktop:
90
+
91
+ ```json
92
+ {
93
+ "mcpServers": {
94
+ "therealcost": {
95
+ "command": "uvx",
96
+ "args": ["--from", "git+https://github.com/NoBanks/therealcost-mcp", "therealcost-mcp"]
97
+ }
98
+ }
99
+ }
100
+ ```
101
+
102
+ ### From a local clone
103
+
104
+ ```bash
105
+ git clone https://github.com/NoBanks/therealcost-mcp
106
+ cd therealcost-mcp
107
+ pip install -e .
108
+ therealcost-mcp # speaks MCP over stdio
109
+ ```
110
+
111
+ Then point your client at the `therealcost-mcp` command (Claude Code: `claude mcp add therealcost -- therealcost-mcp`).
112
+
113
+ ## Tools
114
+
115
+ ### `credit_card_payoff`
116
+
117
+ Months and total interest to clear a card balance paying only the minimum, versus a fixed monthly payment.
118
+
119
+ | Input | Type | Default | Notes |
120
+ | --- | --- | --- | --- |
121
+ | `balance` | number | required | dollars |
122
+ | `apr` | number | required | percent, 24 means 24% |
123
+ | `payment` | number | none | fixed monthly payment to compare |
124
+ | `min_pct` | number | 1 | minimum = this % of the balance |
125
+ | `min_floor` | number | 25 | dollar floor on the minimum |
126
+ | `min_plus_interest` | boolean | true | minimum also includes that month's interest |
127
+
128
+ ```json
129
+ {"name": "credit_card_payoff", "arguments": {"balance": 5000, "apr": 24, "payment": 200}}
130
+ ```
131
+
132
+ Result (abridged): minimum only 234 months and $8,886.95 interest; $200 a month 36 months and
133
+ $2,000.56 interest; link
134
+ `https://therealcost.nohumannearby.com/calculators/credit-card-payoff/?balance=5000&apr=24&minPct=1&minFloor=25&plusInterest=1&fixedPayment=200`
135
+
136
+ ### `debt_consolidation`
137
+
138
+ Current debts versus one consolidation loan, including the origination fee (taken out of the loan, so
139
+ the loan is sized up to total / (1 - fee%)).
140
+
141
+ | Input | Type | Default | Notes |
142
+ | --- | --- | --- | --- |
143
+ | `debts` | array | required | 1 to 10 items of `{balance, apr, payment, name?}` |
144
+ | `loan_apr` | number | required | percent |
145
+ | `loan_term_months` | integer | required | 1 to 600 |
146
+ | `origination_fee_pct` | number | 0 | percent |
147
+
148
+ ```json
149
+ {"name": "debt_consolidation", "arguments": {
150
+ "debts": [{"balance": 6000, "apr": 24.99, "payment": 200},
151
+ {"balance": 3000, "apr": 27.99, "payment": 110},
152
+ {"balance": 2500, "apr": 19.99, "payment": 90}],
153
+ "loan_apr": 13, "loan_term_months": 48, "origination_fee_pct": 5}}
154
+ ```
155
+
156
+ ### `loan_cost_by_term`
157
+
158
+ Monthly payment, total interest and total paid for one loan over several terms.
159
+
160
+ | Input | Type | Default | Notes |
161
+ | --- | --- | --- | --- |
162
+ | `principal` | number | required | dollars |
163
+ | `apr` | number | required | percent |
164
+ | `terms` | integer array | [36, 48, 60, 72, 84] | months; the first two pre-fill the site |
165
+
166
+ ```json
167
+ {"name": "loan_cost_by_term", "arguments": {"principal": 25000, "apr": 8, "terms": [36, 60]}}
168
+ ```
169
+
170
+ Result (abridged): 36 months $783.41 a month; 60 months $506.91 a month.
171
+
172
+ ### `crypto_trade_cost`
173
+
174
+ Trading fee, spread and network fees on a buy and a later sale at the same price, the price rise
175
+ needed to break even, and the yearly cost of recurring buys.
176
+
177
+ | Input | Type | Default | Notes |
178
+ | --- | --- | --- | --- |
179
+ | `amount` | number | required | dollars bought |
180
+ | `fee_pct` | number | required | trading fee per trade, percent |
181
+ | `spread_pct` | number | required | spread per trade, percent |
182
+ | `network_fee_buy` | number | 0 | flat dollars after the buy |
183
+ | `network_fee_sell` | number | 0 | flat dollars to move coins back to sell |
184
+ | `weekly_buy` | number | none | recurring buy amount; adds the yearly cost |
185
+ | `buys_per_year` | integer | 52 | 52 weekly, 26 biweekly, 12 monthly |
186
+ | `flat_fee_per_buy` | number | 0 | flat fee some platforms add on small buys |
187
+
188
+ ```json
189
+ {"name": "crypto_trade_cost", "arguments": {"amount": 1000, "fee_pct": 0.6, "spread_pct": 0.5,
190
+ "network_fee_buy": 2.5, "network_fee_sell": 2.5, "weekly_buy": 25, "flat_fee_per_buy": 0.99}}
191
+ ```
192
+
193
+ ### `emergency_fund`
194
+
195
+ Goal = monthly expenses x months to cover. Months to reach it, and the monthly amount needed to reach
196
+ it by a target.
197
+
198
+ | Input | Type | Default | Notes |
199
+ | --- | --- | --- | --- |
200
+ | `monthly_expenses` | number | required | must-pay expenses per month |
201
+ | `months_covered` | integer | required | 1 to 60 |
202
+ | `saved` | number | 0 | already saved |
203
+ | `monthly_add` | number | 0 | added each month |
204
+ | `apy` | number | 0 | savings APY, percent |
205
+ | `target_months` | integer | 12 | reach the goal in this many months |
206
+ | `target_date` | string | none | `YYYY-MM` or `YYYY-MM-DD`, instead of `target_months` |
207
+
208
+ ```json
209
+ {"name": "emergency_fund", "arguments": {"monthly_expenses": 2500, "months_covered": 3,
210
+ "saved": 500, "monthly_add": 300, "target_date": "2027-10"}}
211
+ ```
212
+
213
+ Result (abridged): goal $7,500.00; 24 months to reach it at $300 a month; $583.33 a month reaches it in 12 months.
214
+
215
+ ### `list_guides`
216
+
217
+ No inputs. Returns the ten guides (title, subtitle, pages, what each covers, price), the complete
218
+ set ($24.95 for all ten, 10 for the price of 5), the starter pack price (guides 1-3 only), and the
219
+ guides link.
220
+
221
+ ```json
222
+ {"name": "list_guides", "arguments": {}}
223
+ ```
224
+
225
+ ### Errors
226
+
227
+ Bad input never crashes the server. It returns:
228
+
229
+ ```json
230
+ {"error": {"type": "validation_error", "message": "Invalid input for credit_card_payoff.",
231
+ "details": [{"field": "apr", "message": "Field required"}]},
232
+ "disclaimer": "Education only. Not financial advice."}
233
+ ```
234
+
235
+ ## Calculator link parameters (for the site)
236
+
237
+ `calculator_url` uses the site's own form field ids as query parameters, so the site can pre-fill
238
+ each form by reading `?name=value` into the field with that id. Numbers are plain (`5000`, `24.99`);
239
+ booleans are `1` or `0`.
240
+
241
+ | Calculator page | Parameters |
242
+ | --- | --- |
243
+ | `/calculators/credit-card-payoff/` | `balance`, `apr`, `minPct`, `minFloor`, `plusInterest`, `fixedPayment` |
244
+ | `/calculators/debt-consolidation/` | `d1b`, `d1r`, `d1p`, `d2b`, `d2r`, `d2p`, `d3b`, `d3r`, `d3p` (balance, APR, payment per debt), `loanApr`, `loanMonths`, `feePct` |
245
+ | `/calculators/loan-term/` | `amount`, `apr`, `termA`, `termB` |
246
+ | `/calculators/crypto-trade-cost/` | `amount`, `feePct`, `spreadPct`, `networkBuy`, `networkSell`, `weekly`, `freq`, `flatFee` |
247
+ | `/calculators/emergency-fund/` | `expenses`, `monthsCover`, `saved`, `monthly`, `apy`, `target` |
248
+
249
+ Notes: unused debt rows are sent as `dNb=0` so the form's example rows are not counted. With more
250
+ than 3 debts the link opens the plain page (the form has 3 rows) and the result says so. Some site
251
+ fields are dropdowns (loan terms, months to cover, target, frequency); a value outside the dropdown's
252
+ options needs the site to add that option or fall back to its default.
253
+
254
+ ## Development
255
+
256
+ ```bash
257
+ pip install -e ".[dev]"
258
+ pytest
259
+ ```
260
+
261
+ `tests/test_calc.py` is a port of the site's `site/tests/calc-math.test.js` (same hand-checked cases
262
+ and the same cross-checks), and `tests/test_server.py` awaits `list_tools` and `call_tool` directly.
263
+
264
+ ## License
265
+
266
+ MIT. The Real Cost by NoBanks Nearby.