ibge-municipalities-list
Retrieve a complete list of municipalities for any Brazilian state using its two-letter abbreviation. This tool provides structured municipal data from IBGE through the Brasil API MCP server.
Instructions
List all municipalities of a Brazilian state by its abbreviation
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uf | Yes | State abbreviation (e.g., SP, RJ) |
Implementation Reference
- src/tools/ibge/index.ts:81-115 (handler)Handler function that fetches municipalities list from Brasil API for given state 'uf', formats it (shows first 30 if more than 50), handles errors.async ({ uf }) => { console.error(`Listing municipalities for state: ${uf}`); const result = await getBrasilApiData(`/ibge/municipios/v1/${uf}`); if (!result.success) { return formatErrorResponse(`Error listing municipalities: ${result.message}`); } // Format the response data const municipalities = result.data; // If there are too many municipalities, limit the display let formattedText; if (municipalities.length > 50) { const first30 = municipalities.slice(0, 30).map((municipality: any) => `${municipality.nome} (Code: ${municipality.codigo_ibge})` ).join("\n"); formattedText = `Municipalities in ${uf} (showing first 30 of ${municipalities.length}):\n${first30}\n\n...and ${municipalities.length - 30} more municipalities.`; } else { const formattedMunicipalities = municipalities.map((municipality: any) => `${municipality.nome} (Code: ${municipality.codigo_ibge})` ).join("\n"); formattedText = `Municipalities in ${uf}:\n${formattedMunicipalities}`; } return { content: [{ type: "text" as const, text: formattedText }] }; }
- src/tools/ibge/index.ts:77-80 (schema)Zod schema defining the input parameter 'uf': state abbreviation (e.g., SP, RJ).{ uf: z.string() .describe("State abbreviation (e.g., SP, RJ)") },
- src/tools/ibge/index.ts:74-116 (registration)Registers the tool 'ibge-municipalities-list' on the MCP server with description, input schema, and handler function.server.tool( "ibge-municipalities-list", "List all municipalities of a Brazilian state by its abbreviation", { uf: z.string() .describe("State abbreviation (e.g., SP, RJ)") }, async ({ uf }) => { console.error(`Listing municipalities for state: ${uf}`); const result = await getBrasilApiData(`/ibge/municipios/v1/${uf}`); if (!result.success) { return formatErrorResponse(`Error listing municipalities: ${result.message}`); } // Format the response data const municipalities = result.data; // If there are too many municipalities, limit the display let formattedText; if (municipalities.length > 50) { const first30 = municipalities.slice(0, 30).map((municipality: any) => `${municipality.nome} (Code: ${municipality.codigo_ibge})` ).join("\n"); formattedText = `Municipalities in ${uf} (showing first 30 of ${municipalities.length}):\n${first30}\n\n...and ${municipalities.length - 30} more municipalities.`; } else { const formattedMunicipalities = municipalities.map((municipality: any) => `${municipality.nome} (Code: ${municipality.codigo_ibge})` ).join("\n"); formattedText = `Municipalities in ${uf}:\n${formattedMunicipalities}`; } return { content: [{ type: "text" as const, text: formattedText }] }; } );
- src/index.ts:29-29 (registration)Top-level call to registerIbgeTools which includes the 'ibge-municipalities-list' tool.registerIbgeTools(server);
- src/utils/api.ts:11-40 (helper)Utility to fetch data from Brasil API endpoints via axios, handles errors, used by the tool handler.export async function getBrasilApiData(endpoint: string, params: Record<string, any> = {}) { try { const url = `${BASE_URL}${endpoint}`; console.error(`Making request to: ${url}`); const response = await axios.get(url, { params }); return { data: response.data, success: true }; } catch (error: any) { console.error(`Error in API request: ${error.message}`); // Handle API errors in a structured format if (error.response) { return { success: false, statusCode: error.response.status, message: error.response.data?.message || error.message, error: error.response.data }; } return { success: false, message: error.message, error }; } }