fixed-income
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., "@fixed-income Calculate YTM for a 4% coupon bond priced at 97.8"
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.
fixed-income-mcp
Fixed-income analytics for AI agents, with the checks that catch the errors models actually make.
Prices fixed-coupon bonds and measures their interest-rate sensitivity. Two things separate it from a calculator: every analytic duration is validated against a convention-free numerical one, and every valuation is tested against the bounds a correct answer has to satisfy.
The pricing and analytics core (bondmath.bond, .pricing, .analytics,
.checks, .daycount, .schedule) is pure standard library. The package as
distributed also installs the MCP SDK,
required by bondmath.server — see As an MCP server for
why that dependency isn't optional.
Why
A language model asked for the modified duration of an ordinary bond returned 3.0942 years. The correct value is 3.1686. It had divided Macaulay duration by one plus the annual yield instead of one plus the periodic yield — the wrong divisor for a bond paying twice a year.
Then it did something more interesting. Its own duration-plus-convexity approximation stopped matching an exact repricing, and it explained the gap as "third-order terms of the Taylor series." For a bond of that maturity and a 100 bp move, the genuine third-order term is 0.09 bp. The residual it was explaining came from its own miscalculated duration, handed back as theory.
A separate session returned a 4.01% yield for a bond trading at 97.80% of par — below the 4.09% current yield, and therefore outside the range of possible answers.
The full write-up is at joselillotrax-cell/bond-desk.
This library is the answer to it: give the agent a tool that does the arithmetic correctly, and have the tool say so out loud.
Related MCP server: leftbrain
Design
Bisection, not Newton-Raphson. Newton converges faster but can diverge, or settle on a value that satisfies the iteration without solving the pricing equation. That is exactly the 4.01% failure. Bisection cannot do it.
Effective duration ships alongside the analytic one. Central differences on the pricing function involve no annualisation, so the numerical figure cannot inherit a convention error. When the two disagree, the analytic one is wrong.
The wrong answer is computed on purpose. Analytics.naive_modified
carries the figure the bad divisor produces. Unusual for a library, but it is
what lets the tools flag the error rather than silently avoid it.
Use
from datetime import date
from bondmath import Bond, DayCount, yield_from_price, analytics, check_consistency
bond = Bond(
face=1000,
coupon_rate=0.04,
frequency=2,
issue=date(2024, 3, 15),
maturity=date(2029, 3, 15),
basis=DayCount.ACT_ACT_ICMA,
)
settle = date(2025, 9, 11)
quote = yield_from_price(bond, settle, 978.00) # 97.80% of par
print(f"{quote.dirty:.4f}") # 997.5652
print(f"{quote.ytm:.4%}") # 4.6867%
metrics = analytics(bond, settle, quote.ytm)
print(f"{metrics.modified:.4f}") # 3.1686 <- correct
print(f"{metrics.naive_modified:.4f}") # 3.0976 <- the common error
print(f"{metrics.effective:.4f}") # 3.1694 <- numerical arbiter
print(check_consistency(bond, settle, quote, metrics))
# [PASS] below_par_ordering: trading below par at 97.8000%, so
# coupon < current yield < YTM must hold: 4.0000% < 4.0900% < 4.6867%
# ...Scenario analysis isolates the true higher-order residual:
from bondmath import scenario
s = scenario(bond, settle, quote.ytm, shock_bp=100)
print(f"{s.exact:.2f}") # 966.55
print(f"{s.residual_bp:+.2f}") # +0.09 bp, not the six the model claimedConventions
ACT/ACT ICMA, 30/360 (US bond basis), ACT/365 and ACT/360. Annual, semi-annual, quarterly and monthly coupons. Schedules are generated backward from maturity, so an off-cycle issue produces a correctly handled irregular first period.
As an MCP server
Six tools, so an agent can stop doing this arithmetic in its head.
Tool | Does |
| Solves yield to maturity from a market price |
| Clean and dirty price at a given yield |
| Duration, DV01, convexity — with both cross-checks |
| Remaining flows, discount factors, present values |
| Exact repricing vs first- and second-order estimates |
| Audits a yield someone else produced |
Two decisions make these usable by a model rather than merely callable.
Units live in the parameter names. A field called coupon_rate invites
the question of whether 4% is 4 or 0.04, and a wrong guess is off by a
factor of a hundred while looking reasonable. Everything here is
coupon_rate_pct, clean_price_pct_of_face, ytm_pct. Nothing to guess.
Every valuation returns its own verdict. Results carry an
all_checks_passed flag and the list of bounds behind it, so the model sees
whether the number is admissible, not just what it is.
Install
pip install bondmathmcp is a required dependency rather than an optional extra — the MCP
registry validates a package's identifier against PyPI by exact project
name, and an extras-qualified name like bondmath[mcp] fails that check. A
plain install has to be enough to run the server.
Then register it. In Claude Desktop, add to claude_desktop_config.json:
{
"mcpServers": {
"fixed-income": {
"command": "fixed-income-mcp"
}
}
}In Claude Code:
claude mcp add fixed-income -- fixed-income-mcpIf the command isn't found: the pip-installed script may not be on the
launching process's PATH. Use the absolute path instead — find it with
which fixed-income-mcp (inside the environment you installed into) and put
that full path in command.
If you're on macOS and the server shows "disconnected" with no clear
error: check ~/Library/Logs/Claude/mcp-server-fixed-income.log before
anything else — the panel's error message is not the real one. Two macOS
specifics bit this project during development: Python 3.14 silently skips
hidden .pth files, and iCloud Drive can mark files inside ~/Desktop as
hidden without warning; separately, ~/Desktop, ~/Documents and
~/Downloads require an explicit permission grant for a launched
subprocess to read from at all. Installing outside those folders (~/dev,
~/code, anywhere not cloud-synced) avoids both.
In practice
Three exchanges from testing this against Claude Desktop, exercised with natural-language questions rather than pre-filled parameters and cross-checked independently against each tool's own output:
"Un compañero me dice que un bono al 4% semestral... cotizando al 97,80%, rinde un 4,01%. ¿Tiene sentido?" — called
check_consistency_tooldirectly rather than recomputing from scratch, correctly identified the 67.67 bp error, and explained why without needing to iterate: "el bono cotiza bajo par, así que obligatoriamente cupón < rendimiento corriente < TIR."
"Un bono al 3,5% que vence en 2032 cotiza a 96,4. ¿Qué rentabilidad me da?" — face value, issue date and payment frequency were all missing. The schema's required
issue_datefield rejected the first call attempt (MCP error -32602: invalid_type); the model disclosed the assumption it then made rather than silently inventing it, and computed both semi-annual and annual scenarios to show the frequency assumption barely moved the answer.
"¿Cuál tiene más riesgo de tipos: el A (4%, vence 2029, cotiza a 98) o el B (2%, vence 2035, cotiza a 85)?" — two chained tool calls, correct verdict (B, 7.43 years vs 2.14), and an explanation that separated the two forces at work: longer maturity and a low coupon that pushes more of the bond's value into the final principal payment. It also flagged, unprompted, that comparing DV01 in currency terms gives a different ratio than comparing modified duration in percentage terms, since the two bonds don't trade at the same price.
Auditing a suspect figure
check_consistency_tool exists for the case that started this project —
checking a number someone already produced:
claimed_ytm_pct 4.01
correct_ytm_pct 4.686736
error_bp -67.67
all_checks_passed false
[FAIL] below_par_ordering: trading below par at 97.8000%, so
coupon < current yield < YTM must hold:
4.0000% < 4.0900% < 4.0100%Install for development
pip install -e ".[dev]"
python -m pytest -q59 tests. Some pin the numbers in the write-up: if someone ever swaps the
divisor back, test_naive_divisor_is_the_one_that_disagrees fails. Others
guard the MCP schema itself — test_every_parameter_carries_a_description
exists because an earlier version of this server shipped with none, which a
model could only have discovered by guessing.
Not covered
Embedded optionality, floating coupons, sinking funds, amortising structures, ex-dividend conventions, credit risk and settlement lag. A teaching and checking instrument, not a trading system.
License
MIT.
Available Tools
6 toolsbond_analytics_toolMeasure interest-rate sensitivityA
Macaulay duration, modified duration, DV01 and convexity.
Supply either a price or a yield, not both.
modified_duration_years divides Macaulay duration by one plus the
PERIODIC yield. naive_modified_duration_years shows what dividing by one
plus the ANNUAL yield would give — the standard error on any bond paying
more than once a year. effective_duration_years is computed numerically
by central differences and uses no annualisation, so it arbitrates between
them. Report the modified figure; the other two are there to prove it.
Inputs: face_value (required), issue_date (required), maturity_date (required), coupon_rate_pct (required), +5 more. Returns: object
cashflow_schedule_toolList a bond's remaining cash flowsA
Remaining payments, with discount factors when a yield is supplied.
The first flow sits a fraction of a period away rather than a whole one. That exponent is what makes an ACT/ACT ICMA yield differ from a naive one, so it is reported explicitly as periods_from_settlement.
Inputs: face_value (required), issue_date (required), maturity_date (required), coupon_rate_pct (required), +4 more. Returns: object
check_consistency_toolCheck a bond valuation for consistencyA
Test a yield someone has already produced against the required bounds.
Use this to audit a figure rather than compute one — for example when checking work, or when a yield appears in a document and its plausibility matters.
A bond priced below par must yield more than its coupon and more than its current yield; above par, the ordering reverses. These bounds need no iteration and reject a whole class of wrong answers immediately. The correctly solved yield is returned too, so the size of any error is visible.
Inputs: face_value (required), issue_date (required), maturity_date (required), claimed_ytm_pct (required), +5 more. Returns: object
price_from_yield_toolPrice a bond from its yieldA
Value a fixed-coupon bond at a given yield to maturity.
Returns clean and dirty price, accrued interest with the day counts behind it, and the consistency checks the valuation satisfies.
Use this when the yield is known and the price is wanted. For the reverse, use yield_from_price_tool.
Inputs: ytm_pct (required), face_value (required), issue_date (required), maturity_date (required), +4 more. Returns: object
scenario_shock_toolReprice after a parallel yield shiftA
Compare an exact repricing against first- and second-order estimates.
residual_bp is the genuine third-and-higher-order term. For a short bond
and a 100 bp move it is a fraction of a basis point. A residual of several
basis points means the duration is wrong, not that the Taylor expansion
was truncated — a distinction worth making explicitly, because attributing
such a gap to higher-order terms is a common and confident mistake.
Supply either a price or a yield, not both.
Inputs: shock_bp (required), face_value (required), issue_date (required), maturity_date (required), +6 more. Returns: object
yield_from_price_toolSolve a bond's yield from its priceA
Solve for the yield to maturity implied by a market price.
Solved by bisection, which cannot converge on a value that satisfies the iteration without solving the pricing equation. The returned checks verify the ordering of coupon, current yield and yield to maturity, which alone rules out a large class of wrong answers.
This is the usual starting point: market prices are observable, yields are derived.
Inputs: face_value (required), issue_date (required), maturity_date (required), coupon_rate_pct (required), +4 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 6 tools
Each tool serves a distinct function: check_consistency audits yields against bounds, price_from_yield prices from a yield, yield_from_price solves for yield from price, bond_analytics computes risk measures, cashflow_schedule lists cash flows, and scenario_shock compares exact repricing to Taylor estimates. No two tools overlap in purpose, and the descriptions make the boundaries clear.
All tool names use snake_case and end with '_tool', but the prefixes vary in structure: some are verb_noun (check_consistency), some are noun_prep_noun (price_from_yield, yield_from_price), and some are noun_noun (bond_analytics, cashflow_schedule, scenario_shock). This is still a consistent and readable style, but it lacks a uniform verb_noun pattern.
Six tools is a well-scoped set for a fixed-income analytics server. Each tool covers a core calculation (pricing, yield solving, consistency checking, analytics, cash flows, scenario analysis) without redundancy or unnecessary bloat.
The tool set covers the main lifecycle of bond analysis: pricing, yield extraction, risk metrics, cash flow scheduling, and scenario testing. It also includes a consistency checker for validation. No critical operation appears missing for the stated domain.
Maintenance
Related MCP Connectors
Industry-standard bond math for AI agents: price, yield, accrued interest, duration, yield-to-worst
Deterministic time-value-of-money and fund-performance tools for AI agents — future value, present value, CAGR, annuities, perpetuities, loan payments, payback, discounted payback, DPI, RVPI and TVPI via Model Context Protocol. Useful for corporate finance, financial projections, financial analysis, quantitative analysis, financial formulas and financial modeling.
15 deterministic validation tools for AI agents: tax IDs (15 countries), VAT, IBAN, LEI, HS codes.
Loan & mortgage calculator, compound interest, ROI, crypto prices, FX conversion for AI agents.
Related MCP Servers
FlicenseNot gradedqualityDmaintenanceEnables AI assistants to perform high-precision Price and Yield calculations for fixed income securities, including institutional risk metrics, using the industry-standard SSCMFI Bond Math Engine.-- AlicenseNot gradedqualityBmaintenanceProvides exact, deterministic tools for math, dates, units, validation, and more to AI agents, returning precise answers with explicit assumptions and warnings instead of model guesses.MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to run probabilistic portfolio analysis workflows, including input validation, instrument verification, simulation preparation, and approved interactive reporting.-
- AlicenseNot gradedqualityBmaintenanceEnables users to compute fixed-income bond prices, cash flow present values, Macaulay and modified duration, and price convexity through an MCP-compatible quantitative finance engine.7MIT