bondmath

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.

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 claimed

Conventions

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
yield_from_price_tool	Solves yield to maturity from a market price
price_from_yield_tool	Clean and dirty price at a given yield
bond_analytics_tool	Duration, DV01, convexity — with both cross-checks
cashflow_schedule_tool	Remaining flows, discount factors, present values
scenario_shock_tool	Exact repricing vs first- and second-order estimates
check_consistency_tool	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 bondmath

mcp 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-mcp

If 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_tool directly 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_date field 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 -q

59 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.