MCP Brasil

Name: MCP Brasil MCP Server
Author: Mcp-Brasil

왜 쓰나요

핵심 기능

70개 이상의 브라질 공공 API 통합
오픈 데이터 하위 집합에는 API 키 불필요
ViaCEP / BrasilAPI / OpenCEP 폴백 체인으로 CEP 조회 항상 성공
자동 속도 제한 처리가 포함된 Receita Federal CNPJ 조회
BCB 일일 환율 및 SELIC 시계열
브라질 개발자 커뮤니티가 유지 관리

라이브 데모

실제 사용 모습

mcp-brasil.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": [
        "mcp-brasil"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": [
        "mcp-brasil"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": [
        "mcp-brasil"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": [
        "mcp-brasil"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-brasil",
      "command": "uvx",
      "args": [
        "mcp-brasil"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-brasil": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-brasil"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add mcp-brasil -- uvx mcp-brasil

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: MCP Brasil

브라질 거래 상대방에 대한 CNPJ 기반 실사 수행

👤 브라질 B2B 판매자, 법률가, 핀테크 운영팀 ⏱ ~10 min intermediate

언제 쓸까: 공급업체와 계약하기 전에 공식 소스에서 법적 상태, 파트너, 주소를 확인하고 싶을 때.

사전 조건

거래 상대방의 CNPJ — 14자리 번호, 형식 있음/없음 모두 가능

흐름

CNPJ 프로필 조회

Use mcp-brasil. Look up CNPJ 33.000.167/0001-01 and tell me legal name, status (ATIVA?), CNAE, capital social, partners.✓ 복사됨

→ 모든 필드가 포함된 구조화된 프로필
주소 교차 확인

Take the registered CEP. Resolve via ViaCEP. Does the city match what Receita reports?✓ 복사됨

→ 일치/불일치 플래그
제재 확인

Check the partners' CPFs against any sanction lists this MCP exposes. Anything?✓ 복사됨

→ 적중 목록 또는 '이상 없음'

결과: 공식 소스에서 2분 만에 뽑은 거래 상대방에 대한 1페이지 실사 메모.

함정

Receita가 과도한 조회를 속도 제한 — 도구가 이미 재시도로 대응하지만 20건 이상 일괄 처리 시 직접 간격을 두세요

함께 쓰기: filesystem

우편 발송 전 브라질 주소(CEP) 일괄 검증

👤 물류, 이커머스, CRM 정리 ⏱ ~15 min beginner

언제 쓸까: 라벨 5000개를 인쇄하기 전에 CEP와 함께 고객 주소 CSV를 정리하고 싶을 때.

사전 조건

CEP 열이 있는 addresses.csv — 모든 CSV 형식; Claude가 열을 자동으로 감지함

흐름

검증

Use mcp-brasil. For every CEP in /data/addresses.csv, fetch via ViaCEP. Append city, state, neighborhood. Flag CEPs that don't resolve.✓ 복사됨

→ 새 열과 플래그 열이 추가된 validated.csv
조정

For mismatches between CRM city and ViaCEP city, suggest the corrected city.✓ 복사됨

→ 차이 보고서

결과: 행별로 소스가 인용된 정리된 주소 목록.

함정

일부 CEP는 'genéricos' (도시 전체) — ViaCEP가 동네 없이 반환하는 것은 정상 — 오류가 아닙니다

함께 쓰기: filesystem

브라질 중심 데이터 분석을 위한 IBGE 지표 조회

👤 브라질 시장을 다루는 데이터 분석가 ⏱ ~20 min intermediate

언제 쓸까: 시/주별 인구, 1인당 GDP 또는 HDI 데이터가 필요할 때.

흐름

지표 목록

List IBGE indicators available via mcp-brasil related to GDP per capita.✓ 복사됨

→ 지표 카탈로그
주별 시계열 조회

Fetch GDP per capita for all 27 estados, latest year. Output to /data/gdp.csv.✓ 복사됨

→ 27행 CSV
통화 레이어 추가

Convert to USD using BCB's official rate as of the same year. Add column.✓ 복사됨

→ USD 열 추가됨

결과: IBGE + BCB에서 소스된 재현 가능한 주별 데이터셋.

함정

IBGE 지표 ID가 가끔 변경됨 — 항상 카탈로그 도구로 시작하세요; ID를 하드코딩하지 마세요

함께 쓰기: filesystem

조합

다른 MCP와 조합해 10배 효율

mcp-brasil + filesystem

주소 또는 CNPJ CSV 일괄 검증

mcp-brasil + postgres

Postgres 테이블에 공공 데이터 열 보강

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
viacep	cep: str	브라질 CEP 조회	free
cnpj_lookup	cnpj: str	브라질 기업 확인	free (rate-limited by Receita)
bcb_rate	currency: str, date?: str	공식 BRL 환율 필요 시 (예: 회계 목적)	free
ibge_indicator	indicator_id: str, geo_level: 'br'\|'uf'\|'municipio', year?: int	공식 통계 조회	free
inpi_search	query: str, kind: 'patent'\|'trademark'	상표/특허 선행 기술 조사	free

비용 및 제한

운영 비용

API 쿼터: 소스별: ViaCEP 무제한, Receita 약 3회/분, BCB 무제한
호출당 토큰: 100~500
금액: 무료
팁: Receita 집약적인 작업은 당일 응답을 로컬 JSON에 캐시하세요

보안

권한, 시크릿, 파급범위

자격 증명 저장: 오픈 데이터 API는 없음

데이터 외부 송신: 각 호출은 해당 공식 API로 전송됩니다 (viacep.com.br, receita, bcb, ibge 등)

실제 사람의 CPF/CNPJ를 전달할 때는 PII로 취급하세요 — 다른 식별자와 동일하게

문제 해결

자주 발생하는 오류와 해결

Receita CNPJ 조회에서 429 반환

속도 제한에 걸렸습니다. 도구가 한 번 재시도하지만 그래도 안 되면 60초 기다리세요.

확인: 대기 후 단일 조회 성공

ViaCEP가 erro: true 반환

CEP가 존재하지 않거나 형식이 잘못되었습니다 — ddddd-ddd 형식을 확인하세요

IBGE 지표가 특정 연도 데이터를 반환하지 않음

일부 지표는 다년도 주기입니다; 카탈로그에서 사용 가능한 periodos를 확인하세요

대안

MCP Brasil 다른 것과 비교

대안	언제 쓰나	단점/장점
BrasilAPI (직접 REST)	MCP 레이어 없이 단일 엔드포인트를 직접 호출하고 싶을 때	BrasilAPI만으로는 단일 CEP/CNPJ 소스지만 mcp-brasil은 70개 이상을 집계합니다
Receita Federal 직접 사용	가장 권위 있는 CNPJ 데이터가 필요하고 캡차 워크플로를 처리할 수 있을 때	UX가 불편하지만 mcp-brasil은 캐시된 오픈 데이터 미러를 사용합니다

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

설치

클라이언트 선택

사용 사례

실전 활용법: MCP Brasil

브라질 거래 상대방에 대한 CNPJ 기반 실사 수행

사전 조건

흐름

함정

우편 발송 전 브라질 주소(CEP) 일괄 검증

사전 조건

흐름

함정

브라질 중심 데이터 분석을 위한 IBGE 지표 조회

흐름

함정

조합

다른 MCP와 조합해 10배 효율

도구

이 MCP가 노출하는 것

비용 및 제한

운영 비용

보안

권한, 시크릿, 파급범위

문제 해결

자주 발생하는 오류와 해결

대안

MCP Brasil 다른 것과 비교

더 보기

리소스