us-gov-data-mcp

미국 정부 데이터용 MCP 서버. AI 어시스턴트에게 어떤 연방 계약이 곧 만료되는지, 또는 지난해 매출이 가장 많았던 상장 기업이 어디인지 물어보세요 — 정부 공식 기록으로 검증할 수 있는 답변을 받을 수 있습니다.

미국 재무부의 USAspending API와 SEC의 EDGAR XBRL 데이터를 기반으로 구축되었습니다. 스크래핑 없음, API 키 없음, 계정 없음, 개인 데이터 없음.

왜 만들었는가

이 두 소스는 모든 것을 공개하지만, 거의 아무것도 조회할 수 없게 합니다.

usaspending.gov는 계약 종료일로 검색할 수 없습니다. 그러나 연방 계약의 수행 기간이 끝나면, 그 작업은 대개 재경쟁(re-compete)을 거쳐야 합니다 — 그리고 이러한 재경쟁은 정부 조달에서 가장 확률이 높은 기회로, 어떤 입찰 공고가 나타나기 몇 달 전에 공개 데이터에서 확인할 수 있습니다.

sec.gov는 한 번에 한 기업씩만 서류를 제공합니다. 사이트에서는 매출이 1,000억 달러를 초과하는 상장 기업이 어디인지, 또는 현금을 가장 많이 보유한 기업이 어디인지 물어볼 방법이 없습니다. SEC의 frames API는 XBRL 태그와 기간 형식을 이미 알고 있다면, 단 한 번의 호출로 전체 약 5,800개 신고 기업에 대해 답할 수 있습니다.

이 서버는 그 사이트들이 답할 수 없는 질문에 답합니다.

Related MCP server: sec-edgar-mcp

네 가지 도구

find_expiring_contracts — 재경쟁

재입찰이 임박한 연방 계약, 현 계약자(incumbent)와 남은 일수 정보. expiring_after_days는 입찰 준비 기간을 설정합니다. 다음 주에 끝나는 계약은 준비할 시간이 없으니까요.

{
  "days_until_expiry": 120,
  "recipient": "PERATON ENTERPRISE SOLUTIONS LLC",
  "amount_usd": 682369225.00,
  "awarding_agency": "General Services Administration",
  "verify_url": "https://www.usaspending.gov/award/..."
}

search_federal_contracts

기관, 키워드, 날짜 또는 금액 기준으로 체결된 계약 검색. 누가 연방 사업을 수주하고 있는지, 기관이 무엇에 지출하는지, 경쟁사의 이력.

screen_public_companies

보고된 재무 지표로 모든 미국 상장 기업을 순위화합니다.

"2023년 매출이 2,000억 달러를 초과한 기업은 어디인가?"

{ "company": "Walmart Inc.", "value": 648125000000, "unit": "USD",
  "period_end": "2023-12-31", "period_type": "annual",
  "verify_url": "https://www.sec.gov/Archives/edgar/data/104169/..." }

company_financial_history

한 기업의 특정 지표 — 매출, 순이익, 자산, 현금 흐름 — 보고 이력을 중복 제거하여, 각 레코드에 서식 유형과 제출일을 포함해 제공합니다.

모든 것이 검증 가능합니다

각 레코드는 해당 데이터가 출처한 정부 서류로 연결되는 verify_url을 포함합니다. 열어서 비교해 보세요.

AI가 개입된 상황에서 이는 가장 중요합니다: 어시스턴트가 금액을 보고할 때, 일련의 과정을 신뢰하기보다 출처와 대조해 확인할 수 있어야 합니다. 값이 공식 기록과 일치하지 않는다면, 그것은 버그입니다 — 이슈를 열어 주세요.

이 서버가 처리해 주는 세 가지 함정

원시 SEC 데이터는 세 가지 특정한 방식으로 오해를 불러일으키며, 각각 조용히 발생합니다 — 오류가 아닌 그럴듯한 잘못된 숫자를 받게 됩니다.

1. 10-Q는 분기와 연간 누계를 동일한 종료일로 보고합니다. 서로 다른 서류의 순이익을 비교하면 3개월 수치와 9개월 수치가 조용히 혼합됩니다. 모든 레코드는 period_type을 포함하며, 이를 기준으로 필터링할 수 있습니다.

2. 동일한 사실이 서로 다른 값으로 여러 서류에 반복됩니다. 올해의 10-K는 작년 수치를 재작성합니다. 기간당 하나의 레코드로 중복 제거되며, 가장 최근 서류가 우선합니다 — SEC 자체의 재작성 처리 방식입니다.

3. 기업은 시간이 지나면서 XBRL 태그를 변경합니다. Microsoft는 2010년까지 Revenues를 사용했고 이후 다른 태그를 사용했습니다. 데이터가 반환되는 첫 번째 태그를 사용하면 오래된 부분 이력을 얻게 됩니다. 이 서버는 모든 태그를 병합합니다.

설치

uvx --from git+https://github.com/groundtruthtools/us-gov-data-mcp us-gov-data-mcp

Claude Desktop — claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "us-gov-data": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/groundtruthtools/us-gov-data-mcp",
        "us-gov-data-mcp"
      ],
      "env": { "SEC_USER_AGENT": "Your Name your@email.com" }
    }
  }
}

모든 MCP 클라이언트에서 작동합니다: Claude Desktop, Claude Code, Cursor, VS Code.

SEC_USER_AGENT 설정을 권장합니다. SEC의 공정 접근 정책은 연락처 주소가 포함된 User-Agent를 요구하며, 이를 포함하지 않은 요청은 403을 받습니다. 기본값이 포함되어 있어 바로 작동하지만, 자신을 식별하는 것이 예의이며 공유 신원에서 벗어날 수 있습니다.

어렵게 배운 한 가지 특이점: 해당 문자열에 URL을 넣지 마세요. SEC는 URL이 포함된 User-Agent에 대해 403을 반환합니다. Your Name your@email.com은 작동하지만, github.com/...을 추가하면 작동하지 않습니다.

아직 PyPI에 없으므로 저장소에서 설치하세요. PyPI에 등록되면 uvx us-gov-data-mcp 한 줄로 설치할 수 있습니다.

솔직한 한계

• 계약: 체결된 계약이지 공개 입찰이 아닙니다. 게시된 입찰은 SAM.gov를 사용하세요.

• 계약: 연방 계약만 해당, 2008 회계연도 이전 데이터는 없음.

• 재경쟁 검색은 지난 1년간 활동이 있는 계약만 포함합니다. USAspending이 결과 페이지 깊이를 제한하기 때문입니다. 오랫동안 활동이 없던 계약은 나타나지 않을 수 있으며, 지나치게 광범위한 검색은 자신 있게 빈 목록을 반환하는 대신 그 사실을 알려줍니다.

• SEC: XBRL 적용 범위는 약 2009년부터 시작하며, 기업이 실제로 태그한 개념만 포함합니다. 소규모 신고 기업은 태그를 덜 사용합니다.

• 보고만 하며 계산하지 않습니다. 비율, 성장률 또는 파생 지표는 없습니다 — 그것은 서류가 아닌 우리의 산술이 되며, 출처와 대조해 검증할 수 없기 때문입니다.

• 투자 조언이 아닙니다. 데이터 재포맷 도구입니다.

Apify에서도 제공

동일한 로직이 설치 없이 호스팅된 도구로 실행됩니다:

• US Federal Contract Awards & Recompete Finder

• SEC EDGAR Financial Data & Company Screener

데이터 출처 및 라이선스

계약: USAspending.gov, 미국 재무부, DATA Act에 따라 공개. 재무 데이터: SEC EDGAR, 미국 증권거래위원회. 둘 다 공개 도메인. 코드: MIT.