Tesouro em Foco

Tesouro em Foco is a free remote MCP server that brings Brazilian government bond (Tesouro Direto) pricing into AI assistants such as Claude, Cursor, and any…

От сообществаРаботаетБез входаГлобальныйБесплатноТолько чтение

Что умеет

Simulate Bond: Simulates a hypothetical Tesouro Direto bond operation at a given trade date and rate, returning the full set of metrics for that operation: price (PU), quotation, Macaulay/modified dur
Simulate Redemption: Simulates an early redemption: a historical acquisition lot (`lot`) and a hypothetical sell (`sell`), returning gross sale pricing plus `netReturns` (IOF, regressive IR, B3 custod
Catalog List: USE THIS BEFORE calling `simulate_bond` to discover available bonds, or to disambiguate a user's reference (e.g. 'IPCA+ 2050' → which exact `maturityDate`?). Lists every Tesouro Direto b

Какие данные видит

Нужен ли аккаунт

Не нужен: сервер работает без входа

Tesouro em Foco is a free remote MCP server that brings Brazilian government bond (Tesouro Direto) pricing into AI assistants such as Claude, Cursor, and any MCP-compatible client.

The engine implements the Brazilian National Treasury's official pricing methodology — validated against 269,000+ real trades — and covers all retail bond types: fixed-rate (LTN, NTN-F), inflation-linked (NTN-B Principal, NTN-B), and retirement/education bonds (Renda+ and Educa+, NTN-B1).

No API key and no signup required: just point your MCP client to the endpoint. Independent educational project; not investment advice.

Список инструментов сервера (7)

Технические названия из tools/list. Нужны только разработчикам.

simulate_bond	Simulates a hypothetical Tesouro Direto bond operation at a given trade date and rate, returning the full set of metrics for that operation: price (PU), quotation, Macaulay/modified duration, and optionally the cash-flow schedule (coupons or installments). USE THIS for ANY question about a Tesouro Direto bond — price, quotation, duration, sale proceeds, payment schedule, etc. Single tool, all metrics. Bulk: up to 10 items per request (5 if any item sets includeSchedule). Output is discriminated by `productFamily` ('prefixado' \| 'ipca' \| 'renda-educa'). The `schedule` field defaults to `null` to keep responses compact (a Renda+ schedule alone has 240 entries). It comes populated as `[{ date, businessDays, flow, cashFlowBrl, presentValue, kind, number? }]` (kind: 'coupon' \| 'principal' \| 'installment') — `flow` is the nominal cash flow before discounting (STN-style flow, not a currency amount); semantics depend on `kind`. `cashFlowBrl` is BRL per one bond unit (face 1000): `flow/100 ×` settlement snapshot of 1000 / `vnaProjected` / `vniProjected`, truncated to centavos (T-2 floor) — not a forecast of BRL actually credited on each payment date for indexed families (VNA on IPCA+ with coupons, VNI on Renda+/Educa+; both move with IPCA accrual); discounted sum of `cashFlowBrl` may differ slightly from PU (T-6). Only when the caller passes `includeSchedule: true` AND the bond family supports a schedule (zero-coupon families like prefixado / ipca-mais never have one). Whenever a field is null, a structured warning in `meta.warnings[]` with `code` and `field` explains why. Every response also carries a `calculation` object (discriminated by `kind`: 'prefixado-zero' \| 'prefixado-semestrais' \| 'ipca' \| 'renda-educa') with the intermediate values used by the engine — business days to maturity, truncated discount exponent, discount factor, VNA/VNI base + projected, IPCA monthly rate, and (when auto-fetched) `automaticIpcaValidFrom`. For IPCA-linked families the `indexProjection` also splits the two projection legs: `monthsBeyondVnaBase` / `monthsCompounded` / `compoundedFactor` (the whole-month forward compounding) versus `exponent` (the sub-month pro-rata). Use it to audit a price against the official methodology without re-running it. Inputs: `tradeDate` (YYYY-MM-DD) is the negotiation date — NOT the settlement date. `side` ('investorBuy' \| 'investorSell', optional but recommended when direction is known): semantic intent of the operation. When provided, the engine derives the correct `settlementConvention` automatically — 'investorBuy' -> 'D+1'; 'investorSell' -> 'D+0' if tradeDate >= 2021-09-13 (same-day sell-back rule), else 'D+1'. Omit `side` when simulating for pure pricing purposes without a specific trade direction. `settlementConvention` ('D+0' \| 'D+1', optional): advanced override — when omitted, the engine derives from `side` (or defaults to 'D+1' when both are omitted). If both `side` and `settlementConvention` are provided and conflict, the explicit `settlementConvention` is used and a NONSTANDARD_SETTLEMENT_FOR_SIDE warning is emitted. The response echoes `side` (when provided), `settlementConvention` (resolved), and `settlementDate`. `includeSchedule` (default false) opts in to coupon/installment detail. `annualRate` MUST be a decimal string (e.g. '0.1423' for 14.23%, never '14.23'). Bond identification: prefixado/IPCA+ require `maturityDate`; Renda+/Educa+ require `conversionYear` OR `maturityYear`. Optional overrides: `vnaBase`+`ipcaMonthlyRate` for IPCA+ types, `vniBase`+`ipcaMonthlyRate` for Renda+/Educa+ (auto-fetched if omitted). `ipcaMonthlyRate` is the current-month ANBIMA projection used ONLY for the sub-month pro-rata — it does NOT compound whole months forward. For a future-dated valuation (settlement months/years ahead), pass `ipcaForwardMonthlyRate` (assumed monthly IPCA) to project the VNA/VNI base forward over the whole-month gap; it is ignored when `vnaBase`/`vniBase` is overridden. Note `ipcaForwardMonthlyRate` and `annualRate` are orthogonal assumptions: the forward rate is the inflation that grows the VNA/VNI base, while `annualRate` is the REAL yield (the '+X%' of IPCA+X%) that discounts it — for IPCA-linked types it does NOT include inflation. A future-dated valuation needs BOTH set to the future scenario; passing `ipcaForwardMonthlyRate` with today's `annualRate` models future inflation at today's real yield. Warning catalog (`meta.warnings[]`, each `{ code, field?, message }`): `NONSTANDARD_SETTLEMENT_FOR_SIDE` (both `side` and `settlementConvention` were provided and the explicit convention differs from the standard for that side — explicit value was used); `SYNTHESIZED_BOND` (bond not in catalog, synthesized for historical simulation); `SETTLEMENT_BEFORE_LAUNCH` (settlement predates the bond's launch date); `IPCA_STALE` (auto IPCA projection is over 35 days old vs settlement); `IPCA_PROJECTION_MISSING` (historical settlement before the earliest bundled IPCA projection — engine falls back to ipcaMonthlyRate=0, using the VNA of the nearest past day-15 without pro-rata; pass an explicit ipcaMonthlyRate for better precision); `IPCA_FORWARD_RATE_IGNORED` (both a `vnaBase`/`vniBase` override and `ipcaForwardMonthlyRate` were supplied — the override is authoritative so the forward rate was ignored); `IPCA_FORWARD_GAP_NOT_COMPOUNDED` (settlement is N whole months beyond the last published VNA/VNI and no `ipcaForwardMonthlyRate` was supplied — the gap was NOT compounded onto the base, only the sub-month pro-rata; pass `ipcaForwardMonthlyRate` for a future-dated valuation, or refresh bundled VNA data if the settlement is actually near-term); `SUSPICIOUS_RATE` (annualRate > 1.0 — likely passed as percentage); `CALENDAR_LAW_SWITCH` (tradeDate predates Lei 14.759/2023; legacy calendar without Nov 20 holiday is in use); `TRADE_DATE_NON_BUSINESS_DAY` (tradeDate is a weekend, holiday, or market interruption — settlement was rolled forward to the next business day, so D+0 and D+1 may resolve to the same date); `NOT_INCLUDED` (field could exist but caller did not request it — set the matching include* flag, e.g. schedule on coupon/stream families); `CASHFLOW_BRL_SETTLEMENT_VNA_SNAPSHOT` (only when `includeSchedule: true` for `bondType` `ipca-mais-com-juros-semestrais` — each `schedule[].cashFlowBrl` uses the settlement VNA snapshot; see `message`); `CASHFLOW_BRL_SETTLEMENT_VNI_SNAPSHOT` (only when `includeSchedule: true` for `bondType` `renda-mais` or `educa-mais` — each `schedule[].cashFlowBrl` uses the settlement VNI snapshot; see `message`). All values are pre-tax (gross), based on hypothetical inputs — this is a simulation, NOT a real-time market quote nor an offer to trade. IR and IOF apply on actual operations. Each bulk row returns `{ input, ok: true, result }` or `{ input, ok: false, error }`. Before calling, use `catalog_list` if you need to discover available bonds or disambiguate the user's reference.
simulate_redemption	Simulates an early redemption: a historical acquisition lot (`lot`) and a hypothetical sell (`sell`), returning gross sale pricing plus `netReturns` (IOF, regressive IR, B3 custody) and annualized gross/net rates (du/252). USE THIS for "quanto recebo líquido se vender?", IR/IOF/custódia on a held lot, or comparing gross vs net redemption proceeds. `lot` takes exactly one of `price` (exact PU — preferred, from the B3 statement) or `rate` (decimal string; engine derives PU). `sell` takes `rate` only (sell by price is not supported). Optional per-leg IPCA scenario: `vnaBase`/`vniBase`/`ipcaMonthlyRate`. For a future-dated `sell` (redemption months/years ahead), also pass `sell.ipcaForwardMonthlyRate` (assumed monthly IPCA) to project the VNA/VNI base forward over the whole-month gap — otherwise the base stays frozen at the last published day-15 and an IPCA_FORWARD_GAP_NOT_COMPOUNDED warning is emitted. `lot` settles D+1; `sell` uses Tesouro sell-back conventions (D+0 when tradeDate >= 2021-09-13). Coupons/installments between lot and sell are NOT tax-modeled (`INTERMEDIATE_FLOWS_TAX_NOT_MODELED`). Tax/fee estimate — not investment or tax advice. Bulk: up to 10 items.
catalog_list	USE THIS BEFORE calling `simulate_bond` to discover available bonds, or to disambiguate a user's reference (e.g. 'IPCA+ 2050' → which exact `maturityDate`?). Lists every Tesouro Direto bond currently in the official catalog, grouped by family. Each product includes `launchDate` and `maturityDate`; Renda+/Educa+ also include `conversionDate` and `installments` (240 monthly payments for Renda+, 60 for Educa+). The `year` field meaning depends on family: - prefixado / IPCA+: catalog maturity-year key (e.g. 2031 → maturity in 2031). - Renda+ / Educa+: the conversion year shown on the label (e.g. Renda+ 2065 → conversion on 15 Jan 2065, NOT redemption year). Final redemption is ~20 years later for Renda+ and ~5 years later for Educa+. Note: `simulate_bond` accepts bonds outside this catalog too (older maturities for historical simulation) — those calls succeed with a `SYNTHESIZED_BOND` warning in `meta.warnings[]` indicating the product was synthesized. Returns: array of `{ type, label, products: [{ year, maturityDate, launchDate, conversionDate?, installments? }] }`.
price_history_lookup	Looks up historical published rates and prices for Tesouro Direto bonds on specific dates. Accepts a bulk array of queries (up to 50). Each query: productId + referenceDate + exactly one paper identifier (maturityDate, maturityYear, or conversionYear for Renda+/Educa+). Returns official STN data for that date, or found=false. Use when the user asks for the official published rate or unit price on a specific past date (e.g. "what was the IPCA+ 2035 rate in March 2024?"). Each result has optional `investorBuy` and `investorSell` objects with `{ rate, price }`: - `investorBuy` — investor PURCHASE side (STN's Taxa de Venda / PU de Venda). This is the standard quoted rate. - `investorSell` — investor SELL-BACK side (STN's Taxa de Compra / PU de Compra). Normally investorSell.rate > investorBuy.rate. Rates are decimal fraction strings (e.g. `'0.0737'` = 7.37% a.a.) — same convention as `simulate_bond` and `live_quotes_lookup`.
price_history_series	Returns a time series or aggregate statistics for a single Tesouro Direto bond over a date range. Required paper selector: this tool queries ONE bond, not a whole product family. Always provide exactly one of `maturityDate`, `maturityYear`, or `conversionYear`. Use `conversionYear` only for `renda-mais` / `educa-mais`; for Prefixado/IPCA+/Selic/IGPM use `maturityDate` or `maturityYear`. If the user did not specify a maturity, call `catalog_list` first or ask for the maturity. Two modes via `aggregate`: - `'none'` (default): raw daily points, each with `investorBuy: { rate, price }` and `investorSell: { rate, price }`. Sub-sample with `step`: 'daily' / 'weekly' / 'monthly'. Max 1000 points; truncated=true if exceeded. Optional pagination: `limit` (1-200) + `offset` + `order` ('asc'\|'desc') — response then carries `meta.page { total, offset, limit }` and the 1000-point cap does not apply. - `'stats'`: per side (`investorBuy` / `investorSell`) over the window: min/max/avg/count for rate and price, plus rate-only percentiles `p25`/`p50`/`p75` (nearest-rank — actually published values), `last` (most recent rate) and `lastPercentile` (0-100: share of the window strictly below `last`). Compact single-object response — prefer this for "is today's rate high?" questions. Field semantics: - `investorBuy` — investor PURCHASE side (STN's Taxa de Venda / PU de Venda). This is the standard quoted rate. - `investorSell` — investor SELL-BACK side (STN's Taxa de Compra / PU de Compra). Normally investorSell.rate > investorBuy.rate. Use when the user asks for a time series or aggregate stats (e.g. rate evolution over 12 months, min/max rate in a year). Rates are decimal fraction strings (same as `price_history_lookup`, `simulate_bond`, `live_quotes_lookup`).
price_history_ranking	Ranks every bond in the active Tesouro Direto catalog by where its latest published rate sits within its own history — in ONE call. Prefer this for questions like "which bonds have rates near their historical highs?", "how does today's rate compare with the past, across the catalog?", or any cross-bond comparison of rate levels. Do NOT loop `price_history_series` per paper for that. For each catalog paper and each requested window it returns rate stats for one side: `min`/`max`, nearest-rank percentiles `p10`/`p25`/`p50`/`p75`/`p90` (always actually published rates), `last` (most recent published rate on or before `to`) and `lastPercentile` (0-100: share of the window strictly below `last` — 92 means the current rate is above 92% of the period, i.e. near the top of its historical range). Inputs (all optional): - `windows`: 1-3 of '30d' \| '90d' \| '1y' \| '5y' \| 'max', default ['1y']. Ranking is ordered by the FIRST window's `lastPercentile` (desc); extra windows add context (e.g. ['1y','max']). - `side`: 'investorBuy' (default — investor PURCHASE rate, STN's Taxa de Venda; the standard quoted rate) or 'investorSell' (sell-back). Only papers currently available for that side are ranked. - `productId`: filter to one family. Only the six catalog families are rankable — 'selic' and 'igpm-mais-com-juros-semestrais' have history but no active catalog entries; for those use `price_history_series`. - `to`: anchor date YYYY-MM-DD (default today UTC) — set a past date for "how did the ranking look then?". Output: `ranking[]` with `productId`, `maturityDate`, `year` (label year — CONVERSION year for renda-mais/educa-mais) and per-window stats; `meta.missing` lists catalog papers with no data in any window (e.g. just launched). Caveats: this is a statistical description of published rates, NOT investment advice, a return forecast, or a recommendation — never present the ranking as "best bonds to buy". `lastPercentile` compares each paper against ITS OWN history only; a high percentile means the rate is high relative to that paper's past, nothing more. Comparing entries across families is meaningful only in that relative sense (a prefixado percentile reflects nominal rates; an ipca-mais percentile reflects real rates). Rates are decimal fraction strings (same as `price_history_series`, `simulate_bond`, `live_quotes_lookup`).
live_quotes_lookup	Looks up live quotes for Tesouro Direto bonds (sourced from the TD website, not STN CSV). Use for current indications only. Each query requires `productId` plus exactly one year field — `maturityYear` is required for all products except renda-mais/educa-mais; for renda-mais/educa-mais use `maturityYear` (calendar maturity year) OR `conversionYear` (label year on the bond name, e.g. 2027 for 'Educa+ 2027') — never both. Omitting the year field will error. Each result has optional `investorBuy` and `investorSell` objects with `{ rate, price }` — the two sides are independent, so one may be present without the other. When `found` is true there is also an optional `fetchedAt` — ISO-8601 UTC from the last site scrape. Field semantics: - `investorBuy` — investor PURCHASE side: rate and price at which the investor buys from the Treasury. - `investorSell` — investor SELL-BACK side: rate and price at which the investor sells back to the Treasury. Normally investorSell.rate > investorBuy.rate. Always consult `catalog_list` to check if the bond is currently available for purchase or sale by Tesouro Direto. `found: true` means at least one of `investorBuy` / `investorSell` is present — each side may be absent independently, so always check which one came back (if you need a single rate and `investorBuy` is missing, use `investorSell`). `found: false` means neither side is present. Possible causes: outside BRT market hours (nights/weekends/holidays), the bond is not currently offered by Tesouro Direto, the year identifier does not match an active offering, or the stored quotes are invalid. When `found` is false fall back to `price_history_lookup` / `price_history_series` for the latest official STN rate. Rates are decimal fraction strings (e.g. `'0.0753'` = 7.53% a.a.) — same convention as `price_history_*` and `simulate_bond`.