brasil-api

BrasilAPI MCP Server exposes tools that query a wide range of BrasilAPI endpoints through a unified interface. The server compiles BrasilAPI client functionality into a set of tools you can invoke from your AI agents or applications, covering data such as postal codes, area codes, banks, holidays, taxes, and more. Each tool corresponds to a BrasilAPI resource, and you can inspect available tools and their parameters via Smithery’s server page or the MCP Inspector to tailor requests to your use case. The server is designed to be run locally or in your deployment environment and can be integrated with Smithery for orchestration and testing.

To use the server, run it with Node.js, then invoke the specific tools through your preferred integration layer (e.g., Smithery, CLI, or code). The project includes tooling to build and inspect the server, and it also supports running with a local copy of BrasilAPI so you can test with updated data before deployment.

Prerequisites:

• Node.js (LTS version) and npm installed on your machine
• Optional: Docker if you prefer containerized runs

Installation steps:

1. Clone the repository or install via npm/xp if published:

   • git clone https://github.com/mauricio-cantu/brasil-api-mcp-server.git
   • cd brasil-api-mcp-server

2. Install dependencies:

   npm install
   

3. Build the server (produces the build/index.js you’ll run):

   npm run build
   

4. (Optional) Run in watch mode for automatic rebuilds during development:

   npm run watch
   

5. Run the server locally with Node:

   node build/index.js
   

6. (Optional) If you prefer Docker, there is a Dockerfile to build and run the image:

   • Build: docker build -t brasil-api-mcp-server .
   • Run: docker run -i brasil-api-mcp-server

Tips:

• Debugging MCP servers can be challenging due to stdio communication; use the MCP Inspector to examine tool definitions and parameters.
• If you modify tools or configurations, run a fresh build to ensure changes are picked up by the running server.
• Ensure your environment has network access to BrasilAPI endpoints, or configure a local mock if needed for development.
• The server can be integrated with Smithery for streamlined deployment and testing across clients like Claude and Cursor.
• When testing locally, verify that the built index.js path in your mcp_config matches the actual location of the compiled server file.