assembly-api-mcp

대한민국 국회 Open API를 Model Context Protocol (MCP) 서버로 제공합니다.

Claude, ChatGPT 등 AI 도구에서 국회의원, 의안, 일정, 회의록, 위원회, 표결, 청원 등 국회 데이터에 실시간으로 접근할 수 있습니다.

주요 기능

7개 Lite / 23개 Full 프로필 도구 — 기본 Lite 프로필로 핵심 기능 제공
276개 국회 API 100% 접근 — discover_apis + query_assembly 범용 도구
31개 검증된 API 코드 — 실제 데이터 반환 확인
CLI 지원 — 터미널에서 직접 국회 데이터 조회
이중 Transport — stdio (Claude Desktop) + HTTP (원격 서버)
인메모리 캐싱 — TTL 기반, 정적/동적 데이터 구분
API 모니터링 — 응답 시간 추적, Rate Limit 관리

빠른 시작

상세한 가이드는 QUICK_START.md를 참조하세요.

# 1. 설치
git clone https://github.com/hollobit/assembly-api-mcp.git
cd assembly-api-mcp
npm install && npm run build

# 2. API 키 설정
cp .env.example .env
# .env 파일에 ASSEMBLY_API_KEY 입력 (발급: https://open.assembly.go.kr)

# 3. 테스트
npx tsx src/cli.ts test

Claude Desktop 연동

~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "assembly-api": {
      "command": "node",
      "args": ["/absolute/path/to/assembly-api/dist/index.js"],
      "env": {
        "ASSEMBLY_API_KEY": "your-api-key-here",
        "MCP_PROFILE": "lite"
      }
    }
  }
}

Claude Desktop을 완전히 종료(트레이 포함)한 후 재시작해야 설정이 적용됩니다.

MCP 도구 목록

Lite 프로필 (7개, 기본)

AI가 효율적으로 사용할 수 있도록 핵심 기능을 통합한 프로필입니다.

도구	설명
`search_members`	의원 검색+상세 (이름/정당/선거구, 1건이면 자동 상세)
`search_bills`	의안 검색+상세+상태필터 (계류/처리/최근, bill_id로 상세)
`search_records`	일정+회의록+표결 (type: schedule/meetings/votes)
`analyze_legislator`	의원 종합분석 (인적+발의+표결 한 번에)
`track_legislation`	주제별 법안 추적 (다중 키워드, 심사이력)
`discover_apis`	276개 API 키워드 검색
`query_assembly`	범용 API 직접 호출

Full 프로필 (23개)

MCP_PROFILE=full로 전환하면 기존 23개 개별 도구를 사용할 수 있습니다.

국회의원 (3개)

도구	설명
`get_members`	국회의원 검색 (이름/정당/선거구)
`get_member_detail`	의원 상세 정보
`search_member_activity`	의원 의정활동 (발의법안 + 표결)

의안 (9개)

도구	설명
`search_bills`	의안 검색 (의안명/제안자/위원회)
`get_bill_detail`	의안 상세 조회
`search_all_bills`	의안 통합검색 (전 대수 포함)
`get_pending_bills`	계류의안 목록
`get_processed_bills`	처리의안 목록
`get_recent_bills`	최근 본회의 처리 의안
`get_bill_review`	의안 심사정보
`get_bill_history`	의안 접수/처리 이력
`get_plenary_votes`	본회의 표결정보

일정 / 회의록 (2개)

도구	설명
`get_schedule`	국회 일정 (통합, 90,201건)
`search_meeting_records`	회의록 검색 (본회의/위원회/국감/인사청문회)

위원회 / 표결 / 청원 / 입법예고 (4개)

도구	설명
`get_committees`	위원회 목록 (356건)
`get_vote_results`	의안별 표결 결과
`search_petitions`	청원 검색 (276건)
`get_legislation_notices`	입법예고 조회 (265건)

부속기관 (3개)

도구	설명
`search_library`	국회도서관 자료 검색
`get_budget_analysis`	예산정책처 분석 자료
`search_research_reports`	입법조사처 보고서

범용 (2개) — 276개 API 100% 커버

도구	설명
`discover_apis`	276개 국회 API 키워드 검색
`query_assembly`	임의 API 코드로 직접 호출

CLI 사용법

# 의원 검색
npx tsx src/cli.ts members --party 더불어민주당

# 의원 의정활동
npx tsx src/cli.ts activity --name 이해민

# 의안 검색
npx tsx src/cli.ts bills --name AI

# 의안 상세
npx tsx src/cli.ts bill-detail <BILL_ID>

# 표결 / 계류 / 처리 / 최근
npx tsx src/cli.ts votes
npx tsx src/cli.ts pending
npx tsx src/cli.ts processed
npx tsx src/cli.ts recent

# 전체 API 목록
npx tsx src/cli.ts meta

# API 작동 테스트
npx tsx src/cli.ts test

환경 변수

변수	필수	기본값	설명
`ASSEMBLY_API_KEY`	O	-	열린국회정보 API 키
`DATA_GO_KR_SERVICE_KEY`	X	-	공공데이터포털 ServiceKey
`NANET_API_KEY`	X	-	국회도서관 API 키
`NABO_API_KEY`	X	-	국회예산정책처 API 키
`MCP_PROFILE`	X	`lite`	`lite` 또는 `full`
`MCP_TRANSPORT`	X	`stdio`	`stdio` 또는 `http`
`MCP_PORT`	X	`3000`	HTTP 모드 포트
`LOG_LEVEL`	X	`info`	로그 레벨
`CACHE_ENABLED`	X	`true`	캐시 활성화

API 키 발급

열린국회정보 접속
회원가입 (무료)
로그인 후 마이페이지 > OPEN API > 인증키 발급
발급받은 키를 .env 파일의 ASSEMBLY_API_KEY에 입력

sample 키로 최대 10건까지 테스트할 수 있습니다.

프로젝트 구조

assembly-api/
├── src/
│   ├── index.ts              # MCP 서버 진입점
│   ├── server.ts             # McpServer 초기화 (stdio/HTTP)
│   ├── config.ts             # 환경 변수 설정
│   ├── cli.ts                # CLI 인터페이스
│   ├── api/
│   │   ├── client.ts         # HTTP 클라이언트 (캐싱/모니터링 통합)
│   │   ├── cache.ts          # 인메모리 TTL 캐시 (LRU)
│   │   ├── codes.ts          # 검증된 API 코드 매핑
│   │   ├── monitor.ts        # API 응답 시간 모니터링
│   │   └── rate-limiter.ts   # Rate Limit 추적
│   ├── tools/                # MCP 도구 (16개 파일, 23개 도구)
│   │   ├── lite/             # Lite 프로필 통합 도구 (7개)
│   ├── resources/            # MCP 정적 리소스
│   └── prompts/              # MCP 프롬프트 템플릿
├── tests/                    # 단위 테스트 (248개)
├── examples/
│   └── api-tester.html       # 브라우저 API 테스터
├── docs/
│   ├── api-catalog.md        # 국회 API 276개 전체 목록
│   ├── mcp-api.md            # MCP 도구 ↔ API 매핑
│   └── discovered-codes.md   # 발굴된 API 코드
├── .env.example              # 환경 변수 템플릿
├── Dockerfile                # Docker 이미지
├── docker-compose.yml        # Docker Compose
└── QUICK_START.md            # 빠른 시작 가이드

개발

npm run build      # TypeScript 빌드
npm test           # 테스트 실행
npm run dev        # 개발 모드 (tsx)
npm run cli        # CLI 실행
npm run lint       # 타입 체크 (tsc --noEmit)

Docker

docker compose up -d
# HTTP 모드로 포트 3000에서 실행
# Health check: curl localhost:3000/health

참고 프로젝트

korean-law-mcp — 한국 법률 MCP 서버
data-go-mcp-servers — 공공데이터 MCP 서버

라이선스

MIT License - LICENSE 참조

Korean National Assembly MCP Server