Brasil Data MCP

What alanpcf/brasil-data-mcp MCP server does

alanpcf/brasil-data-mcp MCP server gives compatible AI clients access to Brazilian public data through 15 tools. The tools query BrasilAPI and return structured JSON for common identifiers and reference datasets. Covered sources and domains include Receita Federal company records, CEP address lookup, BACEN bank and economic data, CVM broker records, IBGE states and municipalities, Registro.br domain status, PTAX exchange bulletins, and book metadata from multiple providers.

The project also includes two MCP prompts: analise-cnpj, which guides a structured company analysis, and panorama-economico, which combines current economic rates with upcoming national holidays.

How it works

An MCP client selects a tool based on the user's request, passes an identifier or other supported input, and receives JSON for the agent to interpret. Inputs generally accept Brazilian formats with or without punctuation where applicable, such as masked or unmasked CNPJ, CEP, and ISBN values.

The available operations are deliberately directional. CEP lookup returns an address from a CEP, but does not find a CEP from an address. Bank lookup accepts a COMPE or Febraban code, while name-based searches use the full bank list. Municipality lookup is scoped to one Brazilian state. Similar restrictions apply to DDD, ISBN, broker, and domain queries.

Exchange lookups use PTAX data for one date at a time. When no date is supplied, the service checks the previous day because the source does not expose the current day's quote. A non-trading date returns the most recent prior business-day bulletin.

Setup and configuration

alanpcf/brasil-data-mcp MCP server runs locally through the published npm package. No credentials, API key, or environment variables are required. The direct command is:

npx -y brasil-data-mcp

For Claude Desktop or Cursor, configure an MCP server with npx as the command and -y brasil-data-mcp as its arguments. The README also documents a Claude Code command and a local development setup using Node.js, npm, TypeScript tooling, and the repository build output.

The server can be used with Claude Desktop, Claude Code, Cursor, Windsurf, and other MCP-compatible clients. The listed client configurations use standard stdio transport.

Tools and capabilities

The tool set includes:

• Query company registration details by CNPJ, including status, address, CNAE, partners, capital, and contact information.
• Resolve Brazilian CEPs to state, city, neighborhood, street, and available coordinates.
• Look up banks by code or list BACEN-registered institutions with COMPE and ISPB values.
• Retrieve national holidays for a year, including movable dates, and inspect DDD coverage by state and city.
• Retrieve ISBN-10 or ISBN-13 book metadata from title through available synopsis and source.
• Read current SELIC, CDI, and IPCA values individually or as a combined list.
• Inspect CVM broker registration data by CNPJ and query PTAX quotations for supported foreign currencies.
• List Brazil's 27 federative units or retrieve all municipalities and IBGE codes for one state.
• Check whether a .br domain is available or registered, including DNS hosts, expiration, and suggestions when provided.

Limitations and notes

The data scope is Brazil-specific. CNPJ lookup is not intended for CPF records or foreign companies; CEP lookup does not support international postal codes; and domain checks cover .br only. Holiday lookup covers national holidays, not state or municipal calendars. Economic tools provide current values rather than historical series and support SELIC, CDI, and IPCA only.

Currency lookup supports the 10 currencies listed by the service and does not cover cryptocurrencies or BRL as a foreign currency. Municipality results can be large; São Paulo, for example, has 645 entries. Domain results are not cached and represent the current status returned by the source. Invalid identifier formats should be rejected locally where the tool guidance requires validation before making a request.