Open Economics

Official19 toolsLive

by felipegambettadesouza6-jpg · TypeScript

Discover, resolve, and query official Brazilian economic data with semantic search and provenance.

Open Economics MCP Server

This MCP server provides a read-only semantic routing layer to discover, resolve, and query official Brazilian economic data with provenance. It targets datasets associated with topics including API access and Brazilian central bank (bcb), spanning economics, IBGE, SELIC, and open data formats.

🛠️ Key Features

Read-only access to authoritative Brazilian economic data
Semantic search for discovering and resolving data
Query support with provenance
Exposes MCP endpoint at https://open-economics-data.knbf982hkn.chatgpt.site/api/mcp

🚀 Use Cases

Find official Brazilian economic series using semantic queries
Retrieve stable series via the Stable series API (v1)
Use authoritative data through related REST endpoints (v2)

⚡ Developer Benefits

Semantic API available at /api/v2 and stable series API at /api/v1
Documentation: https://open-economics-data.knbf982hkn.chatgpt.site/en/docs
Runnable examples: https://open-economics-data.knbf982hkn.chatgpt.site/en/guides
Source and issue tracker on GitHub: https://github.com/felipegambettadesouza6-jpg/open-economic

⚠️ Limitations

Read-only: it does not support creating or modifying data (based on the “free, read-only” description)

Topics

apibcbbrazileconomicsibgeopen-dataopenapicloudflare-workerseconomic-datafinancial-datamcpmodel-context-protocoltesouro-nacionaltypescript

Captured live from the server via tools/list.

search_official_data

Start here for a natural-language Brazilian economic-information need in Portuguese or English. Resolves the economic concept independently of current coverage, returns ranked official datasets, stable-series shortcuts, confidence, missing source integrations, and an explicit unresolved/partial state. Use this before any data query when the exact official dataset ID is unknown.

Parameters2

query	string	required	The user's complete economic-data need, including measure, geography, period, and breakdown when known.
limit	integer	optional	Maximum official dataset candidates to return.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "The user's complete economic-data need, including measure, geography, period, and breakdown when known.",
      "type": "string",
      "minLength": 2,
      "maxLength": 300
    },
    "limit": {
      "description": "Maximum official dataset candidates to return.",
      "default": 10,
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

describe_official_dataset

Get identity, publisher, collection, provenance links, query capability, and any stable Open Economics series shortcuts for an exact dataset ID returned by search_official_data. This does not fetch observations.

Parameters1

dataset_id

string

required

Exact ID returned by search_official_data, such as bcb-sgs:432, ibge-aggregates:5932, siconfi:dca, tesouro-rtn:government-central, tesouro-dpf:debt-profile, comexstat:general, anp:fuel-prices, epe:electricity-consumption, mte:formal-employment, or cvm:investment-funds.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "Exact ID returned by search_official_data, such as bcb-sgs:432, ibge-aggregates:5932, siconfi:dca, tesouro-rtn:government-central, tesouro-dpf:debt-profile, comexstat:general, anp:fuel-prices, epe:electricity-consumption, mte:formal-employment, or cvm:investment-funds.",
      "type": "string",
      "pattern": "^(?:(?:bcb-sgs|ibge-aggregates):\\d+|siconfi:(?:rreo|rgf|dca|entes)|tesouro-rtn:government-central|tesouro-dpf:debt-profile|comexstat:general|anp:fuel-prices|epe:electricity-consumption|mte:formal-employment|cvm:investment-funds)$"
    }
  },
  "required": [
    "dataset_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_bcb_series

Retrieve official observations and authoritative schema metadata for an exact BCB SGS dataset ID. Use only after search_official_data identifies the series. Dates, units, periodicity, source, and raw values are preserved; generic access does not guess transformations.

Parameters5

dataset_id	string	required	Exact BCB dataset ID returned by search_official_data.
start	string	optional	Inclusive start date; defaults to three years ago.
end	string	optional	Inclusive end date; defaults to today.
order	string	optional	Observation order by date.
limit	integer	optional	Maximum number of observations to return.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "Exact BCB dataset ID returned by search_official_data.",
      "type": "string",
      "pattern": "^bcb-sgs:\\d+$"
    },
    "start": {
      "description": "Inclusive start date; defaults to three years ago.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "end": {
      "description": "Inclusive end date; defaults to today.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "order": {
      "description": "Observation order by date.",
      "default": "asc",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "limit": {
      "description": "Maximum number of observations to return.",
      "default": 5000,
      "type": "integer",
      "minimum": 1,
      "maximum": 5000
    }
  },
  "required": [
    "dataset_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_bcb_schema

Fetch authoritative metadata for an exact BCB SGS series, including full name, subject hierarchy, periodicity, unit, source, coverage dates, decimals, formula, and warnings. Use when interpreting a BCB series without retrieving observations.

Parameters1

dataset_id

string

required

Exact BCB dataset ID returned by search_official_data.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "Exact BCB dataset ID returned by search_official_data.",
      "type": "string",
      "pattern": "^bcb-sgs:\\d+$"
    }
  },
  "required": [
    "dataset_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_ibge_schema

Fetch official metadata for an IBGE aggregate selected by search_official_data. Always use this before get_ibge_data unless the official variable, locality, and classification IDs are already known. It prevents guessing a measure or dimensional slice.

Parameters1

dataset_id

string

required

Exact IBGE aggregate ID returned by search_official_data.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "Exact IBGE aggregate ID returned by search_official_data.",
      "type": "string",
      "pattern": "^ibge-aggregates:\\d+$"
    }
  },
  "required": [
    "dataset_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_ibge_data

Retrieve an explicit slice of an IBGE aggregate after inspecting its schema. Returns variables containing classification selections, geographies, and observations; official suppression, missing, quality-flag, and zero states remain distinct.

Parameters5

dataset_id	string	required	Exact IBGE aggregate ID returned by search_official_data.
variable	string	required	One or more official variable IDs separated by \|.
periods	string	optional	Recent-period shorthand such as -12, or explicit official period IDs separated by \|.
locality	string	optional	BR or an explicit IBGE geography selection such as N3[35].
classification	string	optional	Explicit classification selections from the schema, such as 11255[90707].

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "Exact IBGE aggregate ID returned by search_official_data.",
      "type": "string",
      "pattern": "^ibge-aggregates:\\d+$"
    },
    "variable": {
      "description": "One or more official variable IDs separated by |.",
      "type": "string",
      "pattern": "^\\d+(?:\\|\\d+)*$"
    },
    "periods": {
      "description": "Recent-period shorthand such as -12, or explicit official period IDs separated by |.",
      "default": "-12",
      "type": "string",
      "pattern": "^(?:-\\d{1,3}|\\d{4,6}(?:\\|\\d{4,6}){0,119})$"
    },
    "locality": {
      "description": "BR or an explicit IBGE geography selection such as N3[35].",
      "default": "BR",
      "type": "string",
      "pattern": "^(?:BR|N\\d{1,2}\\[(?:all|\\d+(?:,\\d+)*)\\])$"
    },
    "classification": {
      "description": "Explicit classification selections from the schema, such as 11255[90707].",
      "type": "string",
      "pattern": "^\\d+\\[(?:all|\\d+(?:,\\d+)*)\\](?:\\|\\d+\\[(?:all|\\d+(?:,\\d+)*)\\])*$"
    }
  },
  "required": [
    "dataset_id",
    "variable"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_siconfi_schema

Get the meaning and required selection fields for an exact SICONFI dataset returned by search_official_data. Use this before get_siconfi_data so entity, reporting period, report type, government branch, and annex are explicit rather than guessed.

Parameters1

dataset_id

string

required

Exact SICONFI dataset ID returned by search_official_data.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "Exact SICONFI dataset ID returned by search_official_data.",
      "type": "string",
      "pattern": "^siconfi:(?:rreo|rgf|dca|entes)$"
    }
  },
  "required": [
    "dataset_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_siconfi_data

Retrieve an explicit official SICONFI DCA, RREO, RGF, or entity-registry selection. First inspect the schema. This tool preserves account, column, annex, period, entity, raw value fields, and upstream provenance without aggregating or substituting concepts.

Parameters9

dataset_id	string	required	Exact SICONFI dataset ID returned by search_official_data.
year	integer	optional	Calendar year of the official report.
entity	integer	optional	Official IBGE entity code.
period	integer	optional	RREO bimestre (1-6) or RGF period (1-3).
periodicity	string	optional	RGF only: four-month (Q) or half-year (S).
report_type	string	optional	Official SICONFI report type for the selected dataset.
power	string	optional	RGF government branch.
sphere	string	optional	Government sphere: municipal, state, federal, or consortium.
annex	string	optional	Exact official annex name from the SICONFI documentation.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "Exact SICONFI dataset ID returned by search_official_data.",
      "type": "string",
      "pattern": "^siconfi:(?:rreo|rgf|dca|entes)$"
    },
    "year": {
      "description": "Calendar year of the official report.",
      "type": "integer",
      "minimum": 2013,
      "maximum": 2100
    },
    "entity": {
      "description": "Official IBGE entity code.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9999999
    },
    "period": {
      "description": "RREO bimestre (1-6) or RGF period (1-3).",
      "type": "integer",
      "minimum": 1,
      "maximum": 6
    },
    "periodicity": {
      "description": "RGF only: four-month (Q) or half-year (S).",
      "type": "string",
      "enum": [
        "Q",
        "S"
      ]
    },
    "report_type": {
      "description": "Official SICONFI report type for the selected dataset.",
      "type": "string",
      "enum": [
        "RREO",
        "RREO Simplificado",
        "RGF",
        "RGF Simplificado"
      ]
    },
    "power": {
      "description": "RGF government branch.",
      "type": "string",
      "enum": [
        "E",
        "L",
        "J",
        "M",
        "D"
      ]
    },
    "sphere": {
      "description": "Government sphere: municipal, state, federal, or consortium.",
      "type": "string",
      "enum": [
        "M",
        "E",
        "U",
        "C"
      ]
    },
    "annex": {
      "description": "Exact official annex name from the SICONFI documentation.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    }
  },
  "required": [
    "dataset_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_comexstat_data

Retrieve a bounded, explicit MDIC Comex Stat export or import slice from 1997 onward. Use comexstat:general only after search_official_data. Select period, dimensions, metrics, and optional official filter codes; partner, product, state, transport, classification, and raw metric fields remain attached to the result.

Parameters9

dataset_id	string	required	The official MDIC Comex Stat dataset identifier.
flow	string	required	Trade direction to retrieve.
from	string	required	First month, YYYY-MM.
to	string	required	Last month, YYYY-MM.
month_detail	boolean	optional	Whether to keep month-level detail in the response.
details	array	optional	Official dimensions to include, up to eight.
metrics	array	optional	Official Comex Stat metrics to return.
filters	array	optional	Optional official dimension filters.
language	string	optional	Language for labels in the upstream response.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "The official MDIC Comex Stat dataset identifier.",
      "type": "string",
      "const": "comexstat:general"
    },
    "flow": {
      "description": "Trade direction to retrieve.",
      "type": "string",
      "enum": [
        "export",
        "import"
      ]
    },
    "from": {
      "description": "First month, YYYY-MM.",
      "type": "string",
      "pattern": "^\\d{4}-(?:0[1-9]|1[0-2])$"
    },
    "to": {
      "description": "Last month, YYYY-MM.",
      "type": "string",
      "pattern": "^\\d{4}-(?:0[1-9]|1[0-2])$"
    },
    "month_detail": {
      "description": "Whether to keep month-level detail in the response.",
      "default": true,
      "type": "boolean"
    },
    "details": {
      "description": "Official dimensions to include, up to eight.",
      "default": [],
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "country",
          "economicBlock",
          "state",
          "via",
          "urf",
          "ncm",
          "subHeading",
          "heading",
          "chapter",
          "section",
          "BECLevel3",
          "BECLevel2",
          "BECLevel1",
          "SITCBasicHeading",
          "SITCSubGroup",
          "SITCGroup",
          "SITCDivision",
          "SITCSection",
          "ISICClass",
          "ISICGroup",
          "ISICDivision",
          "ISICSection"
        ]
      }
    },
    "metrics": {
      "description": "Official Comex Stat metrics to return.",
      "default": [
        "metricFOB"
      ],
      "maxItems": 6,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "metricFOB",
          "metricKG",
          "metricStatistic",
          "metricFreight",
          "metricInsurance",
          "metricCIF"
        ]
      }
    },
    "filters": {
      "description": "Optional official dimension filters.",
      "default": [],
      "maxItems": 6,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "filter": {
            "description": "Official dimension code to filter.",
            "type": "string",
            "enum": [
              "country",
              "economicBlock",
              "state",
              "via",
              "urf",
              "ncm",
              "subHeading",
              "heading",
              "chapter",
              "section",
              "BECLevel3",
              "BECLevel2",
              "BECLevel1",
              "SITCBasicHeading",
              "SITCSubGroup",
              "SITCGroup",
              "SITCDivision",
              "SITCSection",
              "ISICClass",
              "ISICGroup",
              "ISICDivision",
              "ISICSection"
            ]
          },
          "values": {
            "description": "One or more official filter values.",
            "minItems": 1,
            "maxItems": 50,
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 30
                },
                {
                  "type": "number"
                }
              ]
            }
          }
        },
        "required": [
          "filter",
          "values"
        ]
      }
    },
    "language": {
      "description": "Language for labels in the upstream response.",
      "default": "pt",
      "type": "string",
      "enum": [
        "pt",
        "en",
        "es"
      ]
    }
  },
  "required": [
    "dataset_id",
    "flow",
    "from",
    "to"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_anp_fuel_prices

Retrieve auditable fuel and GLP price statistics calculated from official ANP station observations. Omit year and month for the rolling latest four weeks, or provide both for a published monthly file from 2023 onward. Results retain period, product, geography, unit, sample count, source URL, and the disclosed aggregation method while excluding station identity and addresses.

Parameters10

dataset_id	string	required	The official ANP fuel-prices dataset identifier.
fuel_group	string	required	ANP product group to retrieve.
year	integer	optional	Published source year; provide with month for a monthly file.
month	integer	optional	Published source month; provide with year for a monthly file.
geography	string	optional	Geographic aggregation level.
period	string	optional	Reporting period granularity.
state	string	optional	Two-letter Brazilian state code when geography is state or municipality.
municipality	string	optional	Municipality name when geography is municipality.
product	string	optional	Exact ANP product label, for example GASOLINA or ETANOL.
limit	integer	optional	Maximum aggregate rows to return.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "The official ANP fuel-prices dataset identifier.",
      "type": "string",
      "const": "anp:fuel-prices"
    },
    "fuel_group": {
      "description": "ANP product group to retrieve.",
      "type": "string",
      "enum": [
        "gasoline-ethanol",
        "diesel-gnv",
        "glp"
      ]
    },
    "year": {
      "description": "Published source year; provide with month for a monthly file.",
      "type": "integer",
      "minimum": 2023,
      "maximum": 2100
    },
    "month": {
      "description": "Published source month; provide with year for a monthly file.",
      "type": "integer",
      "minimum": 1,
      "maximum": 12
    },
    "geography": {
      "description": "Geographic aggregation level.",
      "default": "country",
      "type": "string",
      "enum": [
        "country",
        "region",
        "state",
        "municipality"
      ]
    },
    "period": {
      "description": "Reporting period granularity.",
      "default": "week",
      "type": "string",
      "enum": [
        "week",
        "month"
      ]
    },
    "state": {
      "description": "Two-letter Brazilian state code when geography is state or municipality.",
      "type": "string",
      "pattern": "^[A-Za-z]{2}$"
    },
    "municipality": {
      "description": "Municipality name when geography is municipality.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "product": {
      "description": "Exact ANP product label, for example GASOLINA or ETANOL.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "limit": {
      "description": "Maximum aggregate rows to return.",
      "default": 1000,
      "type": "integer",
      "minimum": 1,
      "maximum": 5000
    }
  },
  "required": [
    "dataset_id",
    "fuel_group"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_epe_electricity_consumption

Retrieve monthly EPE electricity consumption and consumer counts from 2004 onward. Select a bounded period, country/region/UF geography, consumption classes, and regulated/free market. The response identifies the exact synchronized official workbook version and discloses aggregation across source system rows.

Parameters9

dataset_id	string	required	The official EPE electricity-consumption dataset identifier.
from	string	optional	Inclusive first month, YYYY-MM.
to	string	optional	Inclusive last month, YYYY-MM.
geography	string	optional	Geographic aggregation level.
states	array	optional	Optional official state codes when geography is state.
regions	array	optional	Optional official regions when geography is region.
classes	array	optional	Consumption classes to include.
markets	array	optional	Electricity-market segments to include.
limit	integer	optional	Maximum rows to return.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "The official EPE electricity-consumption dataset identifier.",
      "type": "string",
      "const": "epe:electricity-consumption"
    },
    "from": {
      "description": "Inclusive first month, YYYY-MM.",
      "type": "string",
      "pattern": "^\\d{4}-(?:0[1-9]|1[0-2])$"
    },
    "to": {
      "description": "Inclusive last month, YYYY-MM.",
      "type": "string",
      "pattern": "^\\d{4}-(?:0[1-9]|1[0-2])$"
    },
    "geography": {
      "description": "Geographic aggregation level.",
      "default": "country",
      "type": "string",
      "enum": [
        "country",
        "region",
        "state"
      ]
    },
    "states": {
      "description": "Optional official state codes when geography is state.",
      "default": [],
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "AC",
          "AL",
          "AM",
          "AP",
          "BA",
          "CE",
          "DF",
          "ES",
          "GO",
          "MA",
          "MG",
          "MS",
          "MT",
          "PA",
          "PB",
          "PE",
          "PI",
          "PR",
          "RJ",
          "RN",
          "RO",
          "RR",
          "RS",
          "SC",
          "SE",
          "SP",
          "TO"
        ]
      }
    },
    "regions": {
      "description": "Optional official regions when geography is region.",
      "default": [],
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Centro-Oeste",
          "Nordeste",
          "Norte",
          "Sudeste",
          "Sul"
        ]
      }
    },
    "classes": {
      "description": "Consumption classes to include.",
      "default": [
        "Comercial",
        "Industrial",
        "Outros",
        "Residencial",
        "Rural"
      ],
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Comercial",
          "Industrial",
          "Outros",
          "Residencial",
          "Rural"
        ]
      }
    },
    "markets": {
      "description": "Electricity-market segments to include.",
      "default": [
        "Cativo",
        "Livre"
      ],
      "maxItems": 2,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Cativo",
          "Livre"
        ]
      }
    },
    "limit": {
      "description": "Maximum rows to return.",
      "default": 1000,
      "type": "integer",
      "minimum": 1,
      "maximum": 5000
    }
  },
  "required": [
    "dataset_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_mte_formal_employment_schema

Inspect the official adjusted Novo Caged selection contract, source vintage, measure meanings, available industry IDs, and the constraint that geography and industry come from separate official tables. Use before an industry query.

Parameters1

dataset_id

string

required

The official MTE Novo Caged dataset identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "The official MTE Novo Caged dataset identifier.",
      "type": "string",
      "const": "mte:formal-employment"
    }
  },
  "required": [
    "dataset_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_mte_formal_employment

Retrieve revised monthly Novo Caged stock, admissions, dismissals, balance, and relative change from 2020 onward. Select exactly one official breakdown: country, region, state, or economic activity. The response preserves the MTE workbook vintage and never synthesizes state-by-industry values.

Parameters8

dataset_id	string	required	The official MTE Novo Caged dataset identifier.
from	string	optional	Inclusive first month, YYYY-MM.
to	string	optional	Inclusive last month, YYYY-MM.
breakdown	string	optional	Official breakdown for the employment result.
states	array	optional	Optional official state codes when breakdown is state.
regions	array	optional	Optional official regions when breakdown is region.
industries	array	optional	Exact official activity IDs returned by get_mte_formal_employment_schema; empty means all activities.
limit	integer	optional	Maximum rows to return.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "The official MTE Novo Caged dataset identifier.",
      "type": "string",
      "const": "mte:formal-employment"
    },
    "from": {
      "description": "Inclusive first month, YYYY-MM.",
      "type": "string",
      "pattern": "^\\d{4}-(?:0[1-9]|1[0-2])$"
    },
    "to": {
      "description": "Inclusive last month, YYYY-MM.",
      "type": "string",
      "pattern": "^\\d{4}-(?:0[1-9]|1[0-2])$"
    },
    "breakdown": {
      "description": "Official breakdown for the employment result.",
      "default": "country",
      "type": "string",
      "enum": [
        "country",
        "region",
        "state",
        "industry"
      ]
    },
    "states": {
      "description": "Optional official state codes when breakdown is state.",
      "default": [],
      "maxItems": 27,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "AC",
          "AL",
          "AM",
          "AP",
          "BA",
          "CE",
          "DF",
          "ES",
          "GO",
          "MA",
          "MG",
          "MS",
          "MT",
          "PA",
          "PB",
          "PE",
          "PI",
          "PR",
          "RJ",
          "RN",
          "RO",
          "RR",
          "RS",
          "SC",
          "SE",
          "SP",
          "TO"
        ]
      }
    },
    "regions": {
      "description": "Optional official regions when breakdown is region.",
      "default": [],
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Centro-Oeste",
          "Nordeste",
          "Norte",
          "Sudeste",
          "Sul"
        ]
      }
    },
    "industries": {
      "description": "Exact official activity IDs returned by get_mte_formal_employment_schema; empty means all activities.",
      "default": [],
      "maxItems": 26,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
      }
    },
    "limit": {
      "description": "Maximum rows to return.",
      "default": 1000,
      "type": "integer",
      "minimum": 1,
      "maximum": 5000
    }
  },
  "required": [
    "dataset_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_cvm_investment_funds_schema

Inspect the synchronized CVM daily-report window, official classifications, fund-search contract, measure meanings, and aggregation constraints. Use before querying a fund by name or comparing classes.

Parameters1

dataset_id

string

required

The official CVM investment-funds dataset identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "The official CVM investment-funds dataset identifier.",
      "type": "string",
      "const": "cvm:investment-funds"
    }
  },
  "required": [
    "dataset_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_tesouro_rtn_schema

Inspect RTN table 1.2 account IDs, hierarchy, current-value unit, coverage, source vintage, and above/below-the-line constraints. Use before selecting revenue or expenditure categories.

Parameters1

dataset_id

string

required

The official Tesouro Nacional RTN dataset identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "The official Tesouro Nacional RTN dataset identifier.",
      "type": "string",
      "const": "tesouro-rtn:government-central"
    }
  },
  "required": [
    "dataset_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_tesouro_rtn

Retrieve monthly current-value RTN accounts from 1997 onward. Defaults to total revenue, transfers, net revenue, total expenditure, and the above-the-line primary result; select exact account IDs or search account labels for detail.

Parameters6

dataset_id	string	required	The official Tesouro Nacional RTN dataset identifier.
from	string	optional	Inclusive first month, YYYY-MM.
to	string	optional	Inclusive last month, YYYY-MM.
accounts	array	optional	Exact account IDs returned by get_tesouro_rtn_schema.
query	string	optional	Account-label search; omit accounts to search the full tree.
limit	integer	optional	Maximum account rows to return.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "The official Tesouro Nacional RTN dataset identifier.",
      "type": "string",
      "const": "tesouro-rtn:government-central"
    },
    "from": {
      "description": "Inclusive first month, YYYY-MM.",
      "type": "string",
      "pattern": "^\\d{4}-(?:0[1-9]|1[0-2])$"
    },
    "to": {
      "description": "Inclusive last month, YYYY-MM.",
      "type": "string",
      "pattern": "^\\d{4}-(?:0[1-9]|1[0-2])$"
    },
    "accounts": {
      "description": "Exact account IDs returned by get_tesouro_rtn_schema.",
      "default": [],
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^\\d+(?:\\.\\d+)*$"
      }
    },
    "query": {
      "description": "Account-label search; omit accounts to search the full tree.",
      "type": "string",
      "minLength": 2,
      "maxLength": 120
    },
    "limit": {
      "description": "Maximum account rows to return.",
      "default": 1000,
      "type": "integer",
      "minimum": 1,
      "maximum": 5000
    }
  },
  "required": [
    "dataset_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_tesouro_dpf_schema

Inspect the six versioned RMD annex tables, their distinct units and coverage, category IDs, holder definitions, source publication, and methodological constraints before selecting data.

Parameters1

dataset_id

string

required

The official Tesouro Nacional DPF debt-profile dataset identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "The official Tesouro Nacional DPF debt-profile dataset identifier.",
      "type": "string",
      "const": "tesouro-dpf:debt-profile"
    }
  },
  "required": [
    "dataset_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_tesouro_dpf

Retrieve one official monthly RMD table at a time: debt composition, DPMFi holders, average maturity, average maturity by indexer, monthly cost, or twelve-month cost. Units remain table-specific and are never combined.

Parameters7

dataset_id	string	required	The official Tesouro Nacional DPF debt-profile dataset identifier.
table	string	optional	Versioned RMD table to retrieve.
from	string	optional	Inclusive first month, YYYY-MM.
to	string	optional	Inclusive last month, YYYY-MM.
categories	array	optional	Exact category IDs returned for the selected table by get_tesouro_dpf_schema.
query	string	optional	Category-label search; useful when category IDs are unknown.
limit	integer	optional	Maximum debt-statistics rows to return.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "The official Tesouro Nacional DPF debt-profile dataset identifier.",
      "type": "string",
      "const": "tesouro-dpf:debt-profile"
    },
    "table": {
      "description": "Versioned RMD table to retrieve.",
      "default": "composition",
      "type": "string",
      "enum": [
        "composition",
        "holders",
        "average-maturity",
        "average-maturity-by-indexer",
        "monthly-cost",
        "twelve-month-cost"
      ]
    },
    "from": {
      "description": "Inclusive first month, YYYY-MM.",
      "type": "string",
      "pattern": "^\\d{4}-(?:0[1-9]|1[0-2])$"
    },
    "to": {
      "description": "Inclusive last month, YYYY-MM.",
      "type": "string",
      "pattern": "^\\d{4}-(?:0[1-9]|1[0-2])$"
    },
    "categories": {
      "description": "Exact category IDs returned for the selected table by get_tesouro_dpf_schema.",
      "default": [],
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
      }
    },
    "query": {
      "description": "Category-label search; useful when category IDs are unknown.",
      "type": "string",
      "minLength": 2,
      "maxLength": 120
    },
    "limit": {
      "description": "Maximum debt-statistics rows to return.",
      "default": 1000,
      "type": "integer",
      "minimum": 1,
      "maximum": 5000
    }
  },
  "required": [
    "dataset_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_cvm_investment_funds

Retrieve daily CVM aggregates by official fund classification or resolve a fund/class latest report by CNPJ or name. Net assets and flows are additive; quota values stay fund-level; reported holder totals are not deduplicated people.

Parameters8

dataset_id	string	required	The official CVM investment-funds dataset identifier.
from	string	optional	Inclusive first report date, YYYY-MM-DD.
to	string	optional	Inclusive last report date, YYYY-MM-DD.
breakdown	string	optional	Whether to aggregate by official classification or resolve a fund.
classifications	array	optional	Official fund classifications to include.
funds	array	optional	Unformatted 14-digit fund/class CNPJ values.
query	string	optional	Fund-name search; use only with breakdown=fund.
limit	integer	optional	Maximum fund or classification rows to return.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "description": "The official CVM investment-funds dataset identifier.",
      "type": "string",
      "const": "cvm:investment-funds"
    },
    "from": {
      "description": "Inclusive first report date, YYYY-MM-DD.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "to": {
      "description": "Inclusive last report date, YYYY-MM-DD.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "breakdown": {
      "description": "Whether to aggregate by official classification or resolve a fund.",
      "default": "classification",
      "type": "string",
      "enum": [
        "classification",
        "fund"
      ]
    },
    "classifications": {
      "description": "Official fund classifications to include.",
      "default": [],
      "maxItems": 6,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Ações",
          "Cambial",
          "FMP-FGTS",
          "Multimercado",
          "Não classificado",
          "Renda Fixa"
        ]
      }
    },
    "funds": {
      "description": "Unformatted 14-digit fund/class CNPJ values.",
      "default": [],
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^\\d{14}$"
      }
    },
    "query": {
      "description": "Fund-name search; use only with breakdown=fund.",
      "type": "string",
      "minLength": 2,
      "maxLength": 120
    },
    "limit": {
      "description": "Maximum fund or classification rows to return.",
      "default": 25,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "dataset_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

README.md12 KBView on GitHub

Open Economics API

A free, read-only semantic routing layer for authoritative Brazilian economic data.

Semantic API: https://open-economics-data.knbf982hkn.chatgpt.site/api/v2
Stable series API: https://open-economics-data.knbf982hkn.chatgpt.site/api/v1
MCP: https://open-economics-data.knbf982hkn.chatgpt.site/api/mcp
Ask the data: https://open-economics-data.knbf982hkn.chatgpt.site/en/ask
MCP setup: https://open-economics-data.knbf982hkn.chatgpt.site/en/mcp
Agent installer: llms-install.md
Documentation: https://open-economics-data.knbf982hkn.chatgpt.site/en/docs
Runnable examples: https://open-economics-data.knbf982hkn.chatgpt.site/en/guides
Source and issue tracker: https://github.com/felipegambettadesouza6-jpg/open-economics
Reliability policy: RELIABILITY.md
2.0 release evidence: benchmarks/RELEASE-READINESS.md
Contributing: CONTRIBUTING.md
Security: SECURITY.md

Run a real economic question → · Connect the MCP server →

Open Economics 2.0 starts with a real economic-information need, resolves its meaning independently of current coverage, and then routes it to official data. Its synchronized catalog currently exposes 12,875 BCB SGS series and IBGE aggregates, plus direct SICONFI fiscal-report, MDIC Comex Stat, and ANP fuel-price access and versioned EPE electricity-consumption, MTE Novo Caged, CVM investment-fund, Tesouro RTN fiscal, and RMD Federal Public Debt data (12,886 official datasets in total). The 32 convenient v1 series IDs remain compatible.

Discovery, REST, the existing product, and MCP share one semantic core. A resolved concept is kept separate from availability, so an unsupported need is reported explicitly instead of being silently mapped to a nearby series. Units, dimensions, reference periods, source identifiers, raw values, methodology links, and retrieval provenance travel with the data.

Start with the economic need

bash

curl --fail --silent \
  "https://open-economics-data.knbf982hkn.chatgpt.site/api/v2/search?q=desemprego%20desde%202015"

curl --fail --silent \
  "https://open-economics-data.knbf982hkn.chatgpt.site/api/v2/datasets/ibge-aggregates%3A6381/schema"

For BCB, /api/v2/datasets/bcb-sgs:{code}/observations provides direct series access with authoritative frequency, unit, source, coverage, formula, and warning metadata. For IBGE, inspect /schema, then send explicit variable, periods, locality, and classification selections to /observations. SICONFI DCA, RREO, and RGF use the same dataset routes while retaining entity, reporting period, annex, account, column, and raw value. Official multidimensional structure is preserved instead of flattened away. Comex Stat preserves trade-flow dimensions and metrics. ANP fuel-price queries return period/geography/product aggregates calculated from official station observations, with source counts and the transformation disclosed while station identity and address fields are excluded. EPE and MTE serve compact, versioned snapshots of official workbooks: electricity retains geography/class/market, while adjusted Novo Caged stock and flows retain their separate national, region/state, or economic-activity breakdowns. CVM daily fund reports retain fund/class identity and quota values; classification aggregates sum only additive measures and identify incomplete filing dates. RTN retains its monthly account hierarchy and above-the-line cash/effective-payment conventions. RMD debt statistics keep composition, holder, maturity, and cost tables separate, with their official units, definitions, and publication vintage.

When to use Open Economics

If you already know the exact official identifier and source contract, calling the publisher directly remains the shortest path. Open Economics is useful when the need starts in human language, spans publisher conventions, requires explicit dimensions, or must retain one consistent provenance and error model.

One contract across official sources

The same observation envelope can retrieve BCB IBC-Br (SGS 24363) and IBGE real GDP growth (SIDRA 5932/6561), without maintaining two date and response parsers:

bash

curl --fail --silent "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1/indicators/br-ibc-br/observations?start=2024-01-01"
curl --fail --silent "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1/indicators/br-gdp-real-yoy/observations?start=2024-01-01"

The runnable multi-source Python example uses both series and prints their official provenance and freshness state.

Start with the catalog

bash

curl --fail --silent "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1"
curl --fail --silent "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1/indicators?q=ipca&source=ibge"
curl --fail --silent "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1/indicators/br-ipca-monthly"

GET /api/v1/indicators is the discovery endpoint. Its meta.available_filters field lists every canonical category, frequency, and source value. It accepts:

Parameter	Meaning
`q`	Case-insensitive search across IDs, names, aliases, and official codes
`category`	A canonical category ID such as `inflation` or `interest-rates`
`frequency`	`daily`, `monthly`, `quarterly`, or `annual`
`source`	`bcb` or `ibge`
`limit`	1–500, default 100

Invalid filters are rejected with a structured problem response; they never silently become an empty result set.

Retrieve a series

bash

curl --fail --silent \
  "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1/indicators/br-ipca-monthly/observations?start=2024-01-01&end=2024-12-31"

curl --fail --silent \
  "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1/indicators/br-selic-target/observations?start=2025-01-01&order=desc&limit=12"

curl --fail --silent \
  "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1/indicators/br-selic-target/latest"

Observation requests accept start, end, order=asc|desc, limit=1..5000, and format=json|csv. Dates use YYYY-MM-DD and end cannot be in the future. Daily BCB requests are limited to ten years because SGS applies the same upstream limit.

All JSON series responses use the same envelope:

json

{
  "data": [
    {
      "date": "2024-01-01",
      "period": "2024-01",
      "source_date": "202401",
      "value": 0.42,
      "raw_value": "0.42",
      "status": "observed"
    }
  ],
  "meta": {
    "indicator": { "id": "br-ipca-monthly", "unit_symbol": "%" },
    "provenance": { "upstream_url": "…", "retrieved_at": "…" },
    "returned": 1,
    "available": 1,
    "truncated": false
  }
}

date is the normalized start date for the reference period; period is the frequency-aware identifier (YYYY-MM-DD, YYYY-MM, YYYY-QN, or YYYY). source_date and raw_value are retained exactly from the official publisher. Read meta.indicator.date_semantics before interpreting stock, flow, or moving-quarter series.

Use format=csv for a flat download. CSV rows repeat indicator_id, source_id, source_url, and upstream_url, so exported values retain their provenance outside the JSON envelope.

API surface

Endpoint	Purpose
`GET /api/v1`	Machine-readable API discovery
`GET /api/v1/indicators`	Search and filter the indicator catalog
`GET /api/v1/indicators/:id`	Full indicator metadata, units, semantics, and links
`GET /api/v1/indicators/:id/observations`	Normalized historical values
`GET /api/v1/indicators/:id/latest`	Latest available observation
`GET /api/v1/sources`	Publisher, attribution, and license metadata
`GET /api/v1/openapi.json`	OpenAPI 3.1 description
`GET /api/v1/health`	Router and catalog readiness (does not call publishers)

All endpoints support CORS and GET, HEAD, and OPTIONS. Successful and error responses include X-Request-Id; browser clients can also read cache, timing, and stale-response headers.

Errors and freshness

Errors use application/problem+json with a stable code, HTTP status, human-readable title, explanatory detail, and request_id. Common cases include INVALID_DATE, INVALID_CATEGORY, INDICATOR_NOT_FOUND, UPSTREAM_CONNECTION_ERROR, and UPSTREAM_TIMEOUT.

The API caches successfully normalized source responses in D1 when configured. If a refresh fails and a previous matching snapshot exists, it is returned with meta.stale: true, meta.cache: "stale", and HTTP Warning: 110. A cache read or write failure is treated as a cache bypass, never as a data failure.

The service is currently best-effort and has no uptime SLA. See RELIABILITY.md for the explicit availability, freshness, change-management, and incident-reporting policy.

Sources and correctness

IBGE Aggregates/SIDRA: prices, GDP, industry, retail, services, labor. The adapter requests the exact official period IDs required for each query; IBGE zero, suppression, availability, and quality symbols keep distinct status values.
BCB SGS: rates, FX, activity, credit, fiscal, external-sector, and commodity series. Rows are normalized, sorted, and de-duplicated because upstream ordering is not guaranteed.
Tesouro Nacional / SICONFI: annual accounts, budget execution, fiscal limits, personnel spending, debt, and the government-entity registry.
Tesouro Nacional / RTN: monthly current-value Government Central revenue, transfers, expenditure, and fiscal-result accounts from 1997 onward, in the official hierarchy and R$ million unit.
Tesouro Nacional / RMD: monthly Federal Public Debt composition, DPMFi holders, average maturity, and cost. Each official table keeps its own unit, coverage, definitions, footnotes, and publication vintage.
MDIC / Comex Stat: exports and imports by product, partner, state, transport mode, customs office, and international classifications.
ANP / Levantamento de Preços de Combustíveis: rolling four-week or monthly fuel and GLP station observations, aggregated by explicit period, product, and geography with calculation provenance.
EPE / Consumo Mensal de Energia Elétrica: monthly consumption and consumer counts from 2004 onward by UF, region, class, and captive/free market, with the official workbook version attached.
MTE / Novo Caged: adjusted monthly employment stock, admissions, dismissals, balance, and relative change from 2020 onward by national total, region/state, or economic activity, with the exact official workbook vintage attached and incompatible table dimensions kept separate.
CVM / Informe Diário de Fundos: daily portfolio value, net assets, subscriptions, redemptions, quota values, and reported holders. Queries can compare official classifications or resolve a latest fund/class report by CNPJ or name; quota values are never aggregated and holder totals are not represented as unique people.

There are 32 curated indicators across inflation, interest rates, currencies, activity, labor, credit, fiscal, external, and markets. Values are never fabricated, forward-filled, or silently sign-inverted. BCB NFSP fiscal series retain BCB's financing-requirement sign convention.

BCB catalog data is published under ODbL; preserve its attribution and share-alike obligations when distributing adapted databases. Attribute IBGE as IBGE/SIDRA and retain its source links and terms. Each indicator response has the authoritative URLs and license applicable to that series.

Run locally

Node.js 22.13+ is required.

bash

npm install
npm run dev
npm run lint
npm test
npm run catalog:epe-sync
npm run catalog:mte-sync
npm run catalog:cvm-sync
npm run catalog:rtn-sync
npm run catalog:dpf-sync

Examples are available in examples/python.py, examples/multi_source_python.py, and examples/javascript.mjs. The D1 migration in drizzle/ is the deployment record for cache snapshots.

License

The API implementation is released under the MIT License. Upstream data remains governed by each publisher's own terms and licenses.

Install

Tools (19)

search_official_datadescribe_official_datasetget_bcb_seriesget_bcb_schemaget_ibge_schemaget_ibge_dataget_siconfi_schemaget_siconfi_data

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://open-economics-data.knbf982hkn.chatgpt.site/api/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "open-economics": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://open-economics-data.knbf982hkn.chatgpt.site/api/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

Open Economics MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

search_official_data

describe_official_dataset

get_bcb_series

get_bcb_schema

get_ibge_schema

get_ibge_data

get_siconfi_schema

get_siconfi_data

get_comexstat_data

get_anp_fuel_prices

get_epe_electricity_consumption

get_mte_formal_employment_schema

get_mte_formal_employment

get_cvm_investment_funds_schema

get_tesouro_rtn_schema

get_tesouro_rtn

get_tesouro_dpf_schema

get_tesouro_dpf

get_cvm_investment_funds

Open Economics API

Start with the economic need

When to use Open Economics

One contract across official sources

Start with the catalog

Retrieve a series

API surface

Errors and freshness

Sources and correctness

Run locally

License

Install

Remote endpoint

Related servers