Skip to main content
Glama
guilhermelirio

Brasil API MCP

Brasil API MCP

A Model Context Protocol (MCP) server that provides tools to query various Brazilian data services via the Brasil API.

Overview

Brasil API MCP is a bridge that connects AI assistants to Brazilian public data services through the standardized Model Context Protocol. It provides access to various information such as:

  • Postal Codes (CEP)

  • Company Registration (CNPJ)

  • Bank information

  • Area codes (DDD)

  • IBGE (Brazilian Institute of Geography and Statistics) data

  • Currency exchange rates

  • Domain registration status (.br domains)

Related MCP server: mcp-brasil

Installation

# Clone the repository
git clone https://github.com/guilhermelirio/brasil-api-mcp
cd brasil-api-mcp

# Install dependencies
npm install

# Build the project
npm run build

Usage

To run the server:

npm start

This will start the MCP server that communicates via standard input/output (stdio).

Available Tools

CEP (Postal Codes)

  • cep-search - Query address information from a Brazilian postal code (CEP)

CNPJ (Company Registration)

  • cnpj-search - Query information about a Brazilian company by its CNPJ (National Registry of Legal Entities)

Banks

  • bank-search - Find information about a Brazilian bank by its code

  • bank-list - List all Brazilian banks

DDD (Area Codes)

  • ddd-search - Find information about a Brazilian area code (DDD)

IBGE (Geography and Statistics)

  • ibge-states-list - List all Brazilian states with their information

  • ibge-state-search - Find information about a Brazilian state by its code or abbreviation

  • ibge-municipalities-list - List all municipalities of a Brazilian state by its abbreviation

Cambio (Currency Exchange)

  • cambio-currencies-list - List all available currencies for exchange rates

  • cambio-rate - Get exchange rates for a specific currency on a specific date

Registro BR (Domain Registration)

  • registrobr-domain-check - Check the status and availability of a .br domain name

Integration Examples

Querying a Brazilian Address by Postal Code

// Sample request to the CEP tool
const response = await callMcpTool("cep-search", {
  cep: "01001000"
});

// Response provides address details:
// {
//   cep: "01001000",
//   state: "SP",
//   city: "São Paulo",
//   neighborhood: "Sé",
//   street: "Praça da Sé",
//   service: "viacep"
// }

Getting Currency Exchange Rates

// Sample request to get USD exchange rate
const response = await callMcpTool("cambio-rate", {
  currency: "USD",
  date: "2023-08-10"
});

// Response provides detailed exchange information

Credits

This project uses the Brasil API service, which aggregates various APIs related to Brazilian public data. Special thanks to the Brasil API team for providing this valuable service to the community.

License

MIT © Guilherme Lirio Tomasi de Oliveira

Available Tools

11 tools
bank-listB

List all Brazilian banks

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a list operation but doesn't describe return format, pagination, rate limits, or error conditions. For a tool with zero annotation coverage, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that communicates the core purpose without any wasted words. It's appropriately sized for a simple list tool and front-loads the essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with no parameters and no output schema, the description adequately states what it does. However, without annotations or output schema, it should ideally provide more behavioral context about what the list contains and how it's structured.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters with 100% schema description coverage, so the schema already documents this completely. The description appropriately doesn't add parameter information, maintaining focus on the tool's purpose. Baseline 4 for zero parameters is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('List') and resource ('all Brazilian banks'), making the purpose immediately understandable. However, it doesn't differentiate from its sibling 'bank-search', which might serve a similar purpose with filtering capabilities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to use this tool versus alternatives like 'bank-search'. The description lacks context about use cases, prerequisites, or exclusions, leaving the agent to infer usage patterns.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cambio-currencies-listB

List all available currencies for exchange rates

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states it's a list operation, implying read-only behavior, but doesn't disclose any behavioral traits like pagination, rate limits, authentication requirements, or what format the list returns. For a tool with zero annotation coverage, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose with zero wasted words. It's appropriately sized for a simple list tool and front-loaded with the essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is minimally complete but lacks important context. It doesn't explain what the list returns (e.g., currency codes, names, symbols) or any behavioral aspects. For a read-only list tool, this is adequate but with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage (empty schema). The description doesn't need to add parameter semantics since there are none, and the schema fully documents this. Baseline for 0 parameters is 4, as the description appropriately doesn't discuss non-existent parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List all available') and resource ('currencies for exchange rates'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'bank-list' or 'ibge-states-list' which also list resources, so it doesn't fully distinguish its specific domain.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites, when-not-to-use scenarios, or comparison to sibling tools like 'cambio-rate' (which might provide actual exchange rates rather than currency lists).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cambio-rateB

Get exchange rates for a specific currency on a specific date

ParametersJSON Schema
NameRequiredDescriptionDefault
currencyYesCurrency symbol (e.g., USD, EUR, GBP)
dateYesDate in YYYY-MM-DD format. For weekends and holidays, the returned date will be the last available business day.

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states the basic function but lacks critical details: whether this requires authentication, rate limits, what happens with invalid inputs, the format/scope of returned rates (e.g., against a base currency), or weekend/holiday behavior (though the schema hints at this). For a data retrieval tool with zero annotation coverage, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core purpose and appropriately sized for this straightforward tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (currency exchange data retrieval) and absence of both annotations and output schema, the description is incomplete. It doesn't explain what 'exchange rates' means (rates against what?), doesn't mention error conditions, and provides no information about the return format. The description should compensate for these gaps but doesn't.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both parameters clearly documented in the schema itself. The description adds no additional parameter semantics beyond what's already in the schema (currency symbol format, date format with weekend/holiday behavior). This meets the baseline expectation when schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Get exchange rates'), target resource ('for a specific currency'), and temporal scope ('on a specific date'). It distinguishes this tool from all sibling tools, which handle banking, location, registration, and other data - none involve currency exchange rates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. While it's clearly the only currency rate tool among siblings, there's no mention of prerequisites, limitations, or comparison to hypothetical alternatives like historical rate trends or multi-currency lookups.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ddd-infoC

Get information about a Brazilian area code (DDD) including state and cities

ParametersJSON Schema
NameRequiredDescriptionDefault
dddYesArea code (DDD) to be queried (only numbers, 2 digits)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. While it states what the tool does ('Get information'), it doesn't describe behavioral traits like whether it's a read-only operation, potential rate limits, authentication needs, error handling, or what format the information is returned in. For a query tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core purpose ('Get information about a Brazilian area code') and adds specific details ('including state and cities'). There is zero wasted language, and every word earns its place by clarifying the tool's scope.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (1 parameter, 100% schema coverage) but lack of annotations and output schema, the description is incomplete. It doesn't address what the output looks like (e.g., JSON structure, possible fields), error conditions, or behavioral constraints. For a tool with no structured output documentation, the description should provide more context about the return value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the parameter 'ddd' fully documented in the schema as a 2-digit area code. The description adds no additional parameter semantics beyond what's in the schema—it doesn't explain valid DDD ranges, examples, or edge cases. With high schema coverage, the baseline score of 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Get information') and resource ('Brazilian area code (DDD)') with specific scope ('including state and cities'). It distinguishes from siblings by focusing on area codes rather than banks, currencies, CEP, CNPJ, IBGE data, or domain checks. However, it doesn't explicitly differentiate from potential similar tools (like 'cep-search' which also deals with geographic codes).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when this tool is appropriate (e.g., for area code lookup vs. other geographic searches like 'cep-search' for postal codes) or any prerequisites. The agent must infer usage from the tool name and description alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ibge-municipalities-listC

List all municipalities of a Brazilian state by its abbreviation

ParametersJSON Schema
NameRequiredDescriptionDefault
ufYesState abbreviation (e.g., SP, RJ)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('List') but lacks details on permissions, rate limits, pagination, or return format. This leaves significant gaps for a tool with no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words. It front-loads the core action and resource, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the output looks like (e.g., list format, fields included) or address potential behavioral aspects like error cases or data freshness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds minimal value beyond the input schema, which has 100% coverage. It implies the 'uf' parameter is a state abbreviation but doesn't provide additional context like valid examples beyond 'SP, RJ' or error handling. Baseline 3 is appropriate given the schema does most of the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('List') and resource ('municipalities of a Brazilian state'), making the purpose specific and understandable. It doesn't explicitly distinguish from sibling tools like 'ibge-state-search' or 'ibge-states-list', which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'ibge-state-search' or 'ibge-states-list', nor does it specify prerequisites such as needing the state abbreviation beforehand.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ibge-states-listB

List all Brazilian states with their information

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the tool lists states with information, but doesn't mention what information is included, whether it's paginated, if there are rate limits, or any authentication requirements. This leaves significant behavioral aspects unspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that communicates the core functionality without any unnecessary words. It's appropriately sized for a simple list operation and front-loads the essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter list tool with no output schema, the description is minimally adequate but lacks important context. It doesn't specify what 'information' includes, the format of the response, or how comprehensive the listing is. Without annotations or output schema, more detail would be helpful for the agent to understand what to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters with 100% schema description coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, which aligns with the schema. A baseline of 4 is appropriate for zero-parameter tools that don't need parameter explanations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List') and resource ('Brazilian states with their information'), making the purpose immediately understandable. However, it doesn't differentiate from its sibling 'ibge-state-search', which could be used for similar state-related queries, so it doesn't reach the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'ibge-state-search' or 'ibge-municipalities-list'. It simply states what the tool does without context about appropriate use cases or limitations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

registrobr-domain-checkB

Check the status and availability of a .br domain name

ParametersJSON Schema
NameRequiredDescriptionDefault
domainYesDomain name to check (with or without .br extension)

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions checking 'status and availability' but doesn't specify what status information is returned, whether it's a read-only operation, if there are rate limits, or what the output format looks like. This leaves significant gaps for a tool that presumably queries an external service.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for a simple tool and front-loads the essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with good schema coverage but no annotations or output schema, the description provides basic purpose but lacks important context about what information is returned and behavioral characteristics. It's minimally adequate but has clear gaps in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, with the single parameter 'domain' well-documented in the schema. The description adds no additional parameter semantics beyond what's already in the schema, so it meets the baseline score when schema coverage is high.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Check') and resource ('status and availability of a .br domain name'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools, which are unrelated to domain checking, so it doesn't reach the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives or any contextual prerequisites. It simply states what the tool does without indicating appropriate usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • Changedbank-list1 field changed
      • removedInput schema / additionalProperties
        Removed value: -false
    • Changedcambio-currencies-list1 field changed
      • removedInput schema / additionalProperties
        Removed value: -false
    • Changedibge-states-list1 field changed
      • removedInput schema / additionalProperties
        Removed value: -false
  2. 11 tool updates
    • First observedbank-list
    • First observedbank-search
    • First observedcambio-currencies-list
    • First observedcambio-rate
    • First observedcep-search
    • First observedcnpj-search
    • First observedddd-info
    • First observedibge-municipalities-list
    • First observedibge-state-search
    • First observedibge-states-list
    • First observedregistrobr-domain-check

TDQS

A3.5/5.0

Scored across 11 tools

Disambiguation5/5

Each tool has a clearly distinct purpose targeting different Brazilian data domains: banks, exchange rates, postal codes, company registrations, area codes, IBGE geographic data, and domain checks. There is no overlap in functionality, and an agent can easily distinguish between them based on their specific resource focus.

Naming Consistency4/5

The naming follows a mostly consistent pattern using hyphen-separated words (e.g., bank-list, cep-search), with clear verb-noun or noun-verb structures. Minor deviations exist, such as 'cambio-currencies-list' (noun-noun-verb) and 'registrobr-domain-check' (brand-noun-verb), but overall, the naming is predictable and readable.

Tool Count5/5

With 11 tools, the server is well-scoped for providing Brazilian data services. Each tool serves a distinct and useful purpose, covering key areas like banking, geography, and business data without being overwhelming or sparse, making it efficient for agents to navigate.

Completeness5/5

The tool set offers comprehensive coverage for querying Brazilian data, including banks, exchange rates, postal addresses, company information, area codes, state and municipality details, and domain checks. There are no obvious gaps; it supports a wide range of common data retrieval needs in this domain.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol server that provides AI models with structured access to external data and services, acting as a bridge between AI assistants and applications, databases, and APIs in a standardized, secure way.
    2
    -
  • A
    license
    A
    quality
    C
    maintenance
    An MCP server that connects AI agents to over 200 tools across 27 Brazilian public APIs, covering economic, legislative, transparency, and judicial data. It enables users to query and cross-reference extensive government datasets from sources like IBGE, the Central Bank, and the Brazilian Congress.
    7
    1,777
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables LLMs to query Brazilian public data such as CEP, CNPJ, DDD, exchange rates, banks, and holidays via the Model Context Protocol.
    12
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    MCP Server for accessing 36 Brazilian public data sources and 1 agent, enabling AI agents to query government data on economy, legislation, transparency, judiciary, elections, environment, health, and more.
    MIT