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
    };
  }
}

Brasil API MCP