brasilapi-mcp

직접 작성한 Model Context Protocol(MCP) 서버로, 공개 BrasilAPI를 LLM 클라이언트(Claude Desktop, Claude Code 또는 모든 MCP 호스트)가 호출할 수 있는 도구로 노출합니다. CEP, CNPJ, 은행, FIPE 차량 가격, 공휴일, DDD 지역 번호를 조회할 수 있습니다.

포르투갈어 README

왜 만들었는가

남이 만든 MCP 서버를 사용하는 것은 쉽습니다. 저는 만드는 것도 할 수 있다는 것을 증명하고 싶었습니다. 도구 스키마, 타입이 지정된 HTTP 클라이언트, 그리고 전체를 테스트 가능하게 유지하는 경계까지요. BrasilAPI는 잘 맞습니다. API 키가 필요 없고 공개 데이터를 제공하기 때문에 누구나 이 저장소를 클론해서 바로 실행할 수 있고, 모든 도구는 네트워크에 닿지 않은 채 테스트로 검증됩니다.

Related MCP server: MCP Brasil API

도구

설치

pip install -e .

의존성은 mcp(공식 Python SDK v2)와 httpx뿐입니다.

실행

brasilapi-mcp            # runs the MCP server over stdio (what an MCP client launches)
brasilapi-mcp --help     # prints usage and exits, without opening a socket

서버는 stdio를 통해 MCP를 사용합니다. 보통 직접 실행하지 않습니다. MCP 클라이언트가 서버를 실행하고 통신합니다. python -m brasilapi_mcp.server도 동작합니다.

클라이언트에 연동하기

Claude Desktop — claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "brasilapi": {
      "command": "brasilapi-mcp"
    }
  }
}

brasilapi-mcp가 PATH에 없다면 command를 venv의 스크립트(예: Windows의 .../.venv/Scripts/brasilapi-mcp)로 지정하거나 "command": "python", "args": ["-m", "brasilapi_mcp.server"]를 사용하세요.

Claude Code — 명령어 하나:

claude mcp add brasilapi -- brasilapi-mcp

그런 다음 자연어로 "CEP 01001-000의 주소는 무엇인가요?" 또는 *"2026년 공휴일을 나열해 주세요"*라고 물어보세요. 그러면 모델이 해당 도구를 호출합니다.

설계 — 오프라인에서 테스트하는 이유

네트워크는 주입 가능한 경계 뒤에 있습니다. BrasilAPIClient는 선택적인 httpx.Client/transport를 받으므로 테스트 스위트는 미리 준비된 JSON을 담은 httpx.MockTransport를 전달하고 실제 네트워크 I/O 없이 실행됩니다. 도구 본문은 클라이언트를 명시적으로 받는 단순한 동기 함수의 얇은 래퍼이므로 로직을 개별적으로 단위 테스트할 수 있고, BrasilAPIError는 traceback 대신 모델이 읽을 수 있는 깔끔한 메시지가 됩니다.

테스트

pip install -e ".[dev]"
pytest -q

테스트 스위트는 mock transport를 상대로 클라이언트(모든 엔드포인트, 입력 정규화, 404/500 처리), 도구 로직 함수, 서버의 도구 등록을 다룹니다. 네트워크에는 전혀 닿지 않습니다.

데이터에 관한 참고 사항

BrasilAPI는 공개 서비스이며 키가 필요 없습니다. 이 서버는 비밀을 저장하지 않고 환경 변수를 읽지 않습니다. 실제 응답은 BrasilAPI와 그 업스트림 소스의 소유입니다.

라이선스

MIT — LICENSE를 참조하세요.