tesourodireto-mcp

An MCP server for Brazilian government bonds (Tesouro Direto) — historical prices and yields, current rates, per-maturity statistics and the ANBIMA yield curve — built for LLM agents.

It is the Python/MCP counterpart of the R package GetTDData: same asset codes, same parsing rules, same fields. It talks directly to the official Tesouro Transparente CKAN open data portal, so no R installation is required.

Why this server

• Official data, no R dependency. Downloads precotaxatesourodireto.csv from Tesouro Transparente and reproduces GetTDData::td_get2() semantics.
• Robust downloads. Retries, validates the CSV header before replacing the cache, and falls back to a previously valid cache when the portal is down.
• Local cache. One download per day, stored in ~/.cache/tesourodireto-mcp (configurable), with an in-memory parsed cache for fast repeated calls.
• Token-efficient output. CSV with a short comment header — not thousands of repetitive JSON records. Long series can be aggregated monthly/yearly.
• The whole curve. get_yield_curve scrapes ANBIMA's ETTJ and computes maturity dates with the Brazil/ANBIMA business-day calendar.
• Agent guidance. Server instructions, a static bond catalog resource and an analyze_bond prompt.

Tools

Resources: tesouro://catalog/bond-types. Prompt: analyze_bond.

Output conventions

• yield_bid is a decimal annual rate: 0.1183 means 11.83% p.a. yield_bid_pct and the *_pct statistics are already in percent.
• price_bid is the unit purchase price in BRL (R$).
• asset_code is the bond family plus maturity as DDMMYY, e.g. LTN 010123, NTN-B Principal 150835.
• Data starts in 2005. Daily series are truncated to the most recent max_rows rows; use frequency="monthly" or a narrower range for long histories.

Install

Requires Python 3.10+.

From PyPI, no clone needed:

uvx tesourodireto-mcp

or with pip:

pip install tesourodireto-mcp
tesourodireto-mcp

From source:

git clone https://github.com/msperlin/tesourodireto-mcp.git
cd tesourodireto-mcp
uv sync
uv run tesourodireto-mcp

Or install the checkout as a standalone tool:

uv tool install .
tesourodireto-mcp

Register with OpenCode

Add to ~/.config/opencode/opencode.json (or a project opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "tesourodireto-mcp": {
        "type": "local",
        "command": [
          "/home/msperlin/GitRepo/mcp-servers/tesourodireto-mcp/.venv/bin/python",
          "-m",
          "tesourodireto_mcp"
        ]
      }
    }
  }
}

Or with uv, without hard-coding a virtualenv path:

"command": ["uv", "run", "--directory", "/path/to/tesourodireto-mcp", "tesourodireto-mcp"]

Register with Claude Desktop

{
  "mcpServers": {
    "tesourodireto-mcp": {
      "command": "uvx",
      "args": ["tesourodireto-mcp"]
    }
  }
}

Examples

Ask the agent:

What are the current NTN-B Principal yields and maturities?

How did the LTN 010127 yield evolve in 2024?

Compare the last 10 years of NTN-B Principal yields with the ANBIMA real return curve.

Summarize the inflation implied by today's Brazilian yield curve.

Typical tool calls:

list_bond_types(asset_codes=["NTN-B Principal"])
get_bond_data(asset_codes=["LTN"], first_year=2024, last_year=2024, asset_code="010127")
get_bond_data(asset_codes=["NTN-B Principal"], first_year=2015, frequency="monthly")
get_current_rates(asset_codes=["LFT", "LTN"])
get_bond_stats(asset_codes=["NTN-B Principal"], first_year=2015, max_assets=10)
get_yield_curve()

A live call returns:

# Tesouro Direto — source: Tesouro Transparente (CKAN)
# Retrieved: 2026-11-01T12:00:00+00:00 | data file date: 2026-11-01 | latest ref date: 2026-10-30 | stale cache: no
# yield_bid is a decimal annual rate (0.1183 = 11.83% p.a.); ...
ref_date,yield_bid,yield_bid_pct,price_bid,asset_code,matur_date
2026-10-30,0.118300,11.8300,912.34,LTN 010127,2027-01-01

Configuration

Development

uv sync
uv run pytest              # offline unit + end-to-end MCP stdio tests
uv run python scripts/smoke_test.py   # live test against Tesouro/ANBIMA

The test suite uses a small CSV fixture, so it does not need network access. The smoke test downloads the real dataset and the current ANBIMA curve.

The ANBIMA business-day calendar (src/tesourodireto_mcp/anbima_holidays.txt) was exported from the bizdays Brazil/ANBIMA calendar used by GetTDData, so curve maturity dates match the R package.

Data sources and disclaimer

• Bond data: Tesouro Transparente, the official open data portal of the Brazilian National Treasury.
• Yield curve: ANBIMA.

This project is not affiliated with Tesouro Nacional, ANBIMA or the R package authors. Data is provided as-is; verify before making financial decisions.

License

MIT © Marcelo S. Perlin