Skip to main content
Glama
fixed-income

fixed-income

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

Available Tools

6 tools
bond_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

    A4.2/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides 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
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to run probabilistic portfolio analysis workflows, including input validation, instrument verification, simulation preparation, and approved interactive reporting.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      7
      MIT