open-ALIO-mcp — 공공기관 정보 MCP 서버

Open-source MCP server for Korean public institution information based on ALIO and ALIO Plus.

ALIO·ALIO Plus 기반 공공기관 경영공시와 정부·공공기관 관련 법령·지침·대국민서비스 정보를 AI 클라이언트(Cursor, Claude Desktop 등)가 조회·분석할 수 있도록 연결하는 MCP(Model Context Protocol) 서버입니다.

"한국전력공사의 최근 5년 정원·부채 추이를 보여줘" — 이 한 문장이면 됩니다.

왜 이 프로젝트인가 (Why this matters)

공공기관 정보는 ALIO에 이미 공개되어 있습니다. 그러나 일반 국민과 실무자가 원하는 질문 단위로 접근하기는 어렵습니다.

• 특정 기관의 최근 5년 재무현황은? 유사 기관끼리 정원·부채·보수를 비교하면?
• 이 기관은 어느 부처 소관이고, 채용·시설·서비스 정보는 어디서 확인하나?
• ALIO 공시 수치와 최근 뉴스 보도가 일치하나?

open-ALIO-mcp는 이런 질문에 AI가 바로 답할 수 있도록 공공기관 정보를 MCP tool로 구조화한 공공데이터 접근성 개선 프로젝트입니다. Generic web search가 아니라 한국 공공기관 도메인에 특화된 MCP 서버로, 기관 식별·주무부처·정원/현원·재무지표· 대국민서비스·법령/지침·경영평가까지 공공기관 분석에 필요한 핵심 도메인 구조를 담고 있습니다.

이 프로젝트에서 가장 어려운 부분은 API 하나를 연결하는 것이 아니라, AI가 안전하게 조회·비교·설명할 수 있는 형태로 한국 공공기관 정보를 모델링하는 것이며, 그 기반은 이미 갖춰져 있습니다. 모든 응답이 출처·기준연도·단위·유의사항을 포함하는 source-aware 설계이므로, 출처 추적성이 중요한 공공부문 활용에 적합합니다.

이 MCP로 할 수 있는 것

자연어 질문 하나로 AI가 위 도구를 조합해 출처·단위·유의사항과 함께 답합니다.

기대 효과

일반 국민

• 공공기관 채용·개방시설·지원사업을 한곳에서 검색 — 기관명 별칭(한전·LH 등)만 알아도 조회 가능
• "이 기관이 뭐 하는 곳인지" 설립목적·주요기능을 공식 공시 기반으로 확인
• 기관 관련 최신 뉴스를 동음이의어·중복기사를 걸러 받아볼 수 있음

공공기관 종사자

• 우리 기관과 동종 기관의 인력·보수·복지·재무 지표를 ALIO 공시 수치로 바로 비교
• 정원 vs 현원을 구분한 인력현황 요약으로 "몇 명 재직?" 질의에 명확히 답변
• 공시 주기·항목 분류를 카탈로그로 확인해 "언제·무엇이 공개되는지" 파악

유관 부서·공무원

• 산하·동종 기관 다건 비교·스크리닝으로 국감·기능조정·정책 브리핑 초안 작성 시간 단축
• 언론 이슈와 실제 공시 지표를 교차검증 — 보도와 수치의 괴리를 한 번에 확인
• 공운법·경영지침·예산운용지침 등 공공기관 업무 맥락 법령·지침을 AI 대화 안에서 조회
• 경영평가편람 지표·배점·세부평가내용 검색으로 평가 준비·변경 추적 지원

데이터·연구 활용

• 모든 응답에 source(출처·기준연도)와 caveats(유의사항) 포함 — 추정 대신 결측 명시
• 채용·지표 분포 집계로 수도권 편중, NCS 직무별 수요 등 거시 패턴 분석
• ALIO 공시 페이지에서 수집·검증한 값까지 병합해 xlsx 미제공 항목으로 원천 데이터 확장

(수집 파이프라인은 별도 데이터 저장소에서 관리)

현재 상태 (Current status)

기능 구현 완료, 운영 전환 전 단계의 early-stage 프로토타입. MCP Tools 32개 · Prompts 2종 · Resources 5종.

• 지금 바로 적합한 용도: 로컬 MCP 사용, 공공부문 AI 실험, 개인 분석
• 공개 HTTP/SSE 배포 전 필요한 보강: 인증, rate limit, 감사로그, 데이터 갱신 자동화 등

운영 통제(operational hardening) — 자세한 내용은 SECURITY.md와 docs/roadmap.md 참조

어려운 도메인 모델링(기관 식별·별칭, 공시 주기, 정원/현원 구분, 지표 단위, 출처 표기)은 대부분 프로젝트 안에 이미 구현되어 있고, 남은 과제는 주로 패키징·테스트·데이터 갱신·배포 통제 같은 운영 영역입니다. 이 저장소는 향후 한국 공공부문 AI 지식 레이어(public-sector AI knowledge layer)로 확장하기 위한 기반(foundation)으로 설계되었습니다.

기관 수 355개는 ALIO 공시 단위 기준이며 부설기관 13개를 포함합니다. 독립 지정 기관 수는 342개이고, MCP 응답의 is_subsidiary, parent_org_code, classification_org_type으로 구분합니다.

아키텍처 (Architecture)

데이터 흐름:

flowchart TD
    A[ALIO 공시 엑셀·크롤링] --> D[open-ALIO-mcp]
    B[ALIO Plus / NKOD OpenAPI] --> D
    C[법령·지침·경영평가편람] --> D
    N[네이버 뉴스 API] --> D
    D --> E[Claude Desktop]
    D --> F[Cursor]
    D --> G[기타 MCP 클라이언트]

질의 처리 구조:

flowchart TD
    U[사용자 자연어 질문] --> M[MCP 클라이언트 / AI]
    M --> T[MCP Tools 32종]
    T --> S[보안 래퍼 — 입력 검증·응답 제한]
    S --> L[데이터 레이어]
    L --> A1[로컬 스냅샷 — institutions·metrics·handbook·guidelines]
    L --> A2[온디맨드 API — ALIO Plus·뉴스·법령]
    T --> R["구조화 응답 (data + source + caveats)"]
    R --> M

상세 구조는 docs/architecture.md 참조.

MCP 기능 상세

Tools (32개)

#### 1. 기관 검색·프로필

#### 2. 경영공시·지표

지표 응답에는 공시 주기 주석이 자동 부착되며, 데이터가 비어 있으면 "공시 주기 미도래·미공시 가능성" 안내가 caveats에 추가됩니다.

#### 3. 대국민서비스 (ALIO Plus)

#### 4. 뉴스·통합 분석

get_institution_news는 org_code 없이 query만으로도 동작합니다. sort='date'일 때 기간을 벗어나면 조기 종료해 API 호출을 줄이며, 보도량이 많아 기간을 다 못 덮으면 caveats로 알립니다.

#### 5. 법령·행정규칙·지침

#### 6. 경영평가편람

#### 7. 운영

Prompts (2종)

Resources (5종)

지표 카테고리 (data/metrics/)

아래 공시 기관 수·연도는 data/metrics/_index.json에 집계되어 있습니다. 최신 값은 MCP tool list_metric_categories 또는 get_server_status로 확인하세요.

데이터 승격 주의: finance, budget, executive_pay는 엑셀 기반 metrics에 ALIO 공시 검증값을 병합합니다. 같은 기관·항목·연도에서 값이 충돌하는 그룹은 자동 선택하지 않고 기존 엑셀 값을 fallback으로 유지합니다. 이 저장소에는 병합이 끝난 런타임 데이터만 포함되며, 원천 수집·승격 파이프라인은 별도 데이터 저장소에서 관리합니다.

설치

Quick start with uvx

PyPI 배포판은 소스 체크아웃 없이 바로 실행할 수 있습니다.

uvx open-alio-mcp

첫 실행 때 로컬 data/ 디렉터리가 없으면 GitHub Release의 alio_snapshot.db를 사용자 데이터 디렉터리로 자동 다운로드합니다. 이 스냅샷만으로 기관 검색, 주요 공시 지표, 공시 항목 카탈로그, 지침·경영평가편람 검색을 사용할 수 있습니다.

API key setup

기본 스냅샷 조회에는 API 키가 없어도 됩니다. 다만 라이브 채용·시설·사업 조회, 뉴스 검색, 법령·행정규칙 조회를 쓰려면 아래 키를 설정하세요.

DATA_GO_KR_SERVICE_KEY는 공공데이터포털에서 "기획재정부_공공기관 정보 조회 서비스"를 활용 신청한 뒤 일반 인증키(Decoding) 값을 사용합니다.

LAW_API_OC는 국가법령정보센터 회원가입 후 "Open API 사용 신청"으로 발급받는 OC 값입니다. 보통 가입 이메일의 ID 부분입니다. 예를 들어 [email protected]이면 hong 형태입니다.

NAVER_CLIENT_ID와 NAVER_CLIENT_SECRET은 네이버 개발자센터에서 애플리케이션을 등록하고 "검색" API 사용을 활성화해 발급받습니다.

Source checkout

Source checkout:

git clone https://github.com/gitbosung/open-ALIO-mcp.git open_alio_mcp
cd open_alio_mcp
python -m venv .venv
.venv\Scripts\activate
pip install -e .
copy .env.example .env   # 발급받은 키 입력

.env (키 발급: data.go.kr → "공공기관 정보 조회서비스" 등 활용신청, Decoding 키 사용):

DATA_GO_KR_SERVICE_KEY=발급받은_일반인증키_Decoding값

# (선택) 기관별 뉴스 검색용 — developers.naver.com 앱 등록 후 '검색' API 키 발급
NAVER_CLIENT_ID=
NAVER_CLIENT_SECRET=

# (선택) 법령·행정규칙 조회용 — open.law.go.kr 회원가입 → 'Open API 사용 신청' → OC 발급
# OC는 가입 이메일의 ID 부분 (예: [email protected] → hong)
LAW_API_OC=

Run

open-alio-mcp
python -m open_alio_mcp
uv run open-alio-mcp

Claude Desktop / MCP client package run after publishing. API 키가 필요 없으면 env 블록은 생략해도 됩니다.

{
  "mcpServers": {
    "open-alio": {
      "command": "uvx",
      "args": ["open-alio-mcp"],
      "env": {
        "DATA_GO_KR_SERVICE_KEY": "발급받은_일반인증키_Decoding값",
        "NAVER_CLIENT_ID": "",
        "NAVER_CLIENT_SECRET": "",
        "LAW_API_OC": ""
      }
    }
  }
}

Runtime data is loaded from data/ during source checkout development. Package installs can use OPEN_ALIO_DATA_DIR, OPEN_ALIO_SNAPSHOT_PATH, or the GitHub Release alio_snapshot.db downloaded by ensure_snapshot().

Claude Desktop 설정 파일 위치:

Claude.ai 웹의 원격 Connector URL 방식은 이 저장소에서 아직 제공하지 않습니다. 현재 배포판은 로컬 stdio MCP 서버로 실행됩니다.

데이터를 직접 지정해야 하는 환경에서는 아래 변수를 사용합니다.

$env:OPEN_ALIO_SNAPSHOT_PATH="C:\path\to\alio_snapshot.db"
uvx open-alio-mcp

Troubleshooting:

• uvx를 찾을 수 없으면 uv 설치 문서에 따라 uv를 설치한 뒤 새 터미널을 여세요.
• DATA_GO_KR_SERVICE_KEY 오류가 나면 Encoding 키가 아니라 Decoding 일반 인증키를 넣었는지 확인하세요.
• LAW_API_OC 오류가 나면 open.law.go.kr의 사용 신청 승인 여부와 OC 값을 확인하세요.
• 스냅샷 다운로드가 실패하면 GitHub Release에서 alio_snapshot.db와 alio_snapshot.db.sha256을 직접 내려받아 OPEN_ALIO_SNAPSHOT_PATH로 지정하세요.

Security Notes

• API 키는 코드·README·테스트 파일에 직접 작성하지 말고 .env 또는 배포 환경변수로만 관리하세요.
• API 키를 URL query parameter로 전달하지 마세요. 브라우저 기록, 프록시, 서버 로그에 남을 수 있습니다.
• .env, .env.local, .env.*, 로그 파일은 .gitignore에 포함되어 있으며 커밋하지 않습니다.
• 외부 API 오류 로그는 serviceKey, OC, NAVER_CLIENT_SECRET 등 민감값을 마스킹합니다.
• MCP tool 입력값은 공통 보안 래퍼에서 길이·범위·허용값을 검증하고, 긴 응답은 MAX_RESPONSE_CHARS와 MAX_ITEMS_PER_TOOL 기준으로 제한됩니다.
• 현재 open-alio-mcp / python -m open_alio_mcp 기본 실행은 stdio MCP입니다. HTTP/SSE로 공개 배포하는 경우에는 별도 reverse proxy 또는 앱 서버에서 rate limit, CORS allowlist, security headers를 반드시 적용하세요.
• 운영·공개 배포에서 CORS_ORIGIN=*를 사용하지 말고 공식 서비스 도메인만 허용하세요.
• 사내 내부망 도입 전에는 SSO/인증 연계, 사용자 식별 감사로그, 내부 데이터와 공개 데이터 tool 분리 정책을 확정하세요.

데이터 갱신·스냅샷 빌드

이 저장소는 병합이 끝난 런타임 데이터(`data/`)와 배포 패키지만 포함합니다. ALIO 공시 엑셀·크롤 수집·파싱·검증·승격으로 data/를 만들어내는 데이터 빌드 파이프라인은 별도 데이터 저장소에서 관리합니다. 새 공시 반영은 파이프라인 저장소에서 data/를 갱신한 뒤, 런타임 부분집합을 이 저장소로 동기화하고 아래로 배포 스냅샷을 빌드·릴리스합니다.

.venv\Scripts\python scripts\build_snapshot.py            # data/ → dist/alio_snapshot.db
.venv\Scripts\python tests\test_smoke.py                  # 오프라인 기능 스모크
.venv\Scripts\python scripts\security_smoke_test.py       # 입력 검증 스모크

빌드한 dist/alio_snapshot.db와 dist/alio_snapshot.db.sha256을 GitHub Release에 올리면 uvx open-alio-mcp 사용자가 자동으로 내려받습니다.

법령·지침·경영평가편람

법령·행정규칙은 국가법령정보센터 Open API를 온디맨드로 검색합니다 (로컬 적재 없음). 공공기관 맥락 질의는 alio://related-laws 화이트리스트(공운법·계약사무규칙·경영지침 등)의 공식 명칭으로 검색해 정확도를 높입니다. get_law_text는 기본 목차 모드이며, article='11'처럼 조문을 지정해 본문을 받을 수 있습니다.

지침은 이원화합니다. 「경영에 관한 지침」 등 상시 지침은 law.go.kr 행정규칙으로 조회하고, 연도별 시달 지침(예산운용지침 등)은 파일을 파싱해 data/guidelines/에 적재합니다.

경영평가편람은 HWPX/PDF를 파싱해 data/handbook/에 적재합니다. alio://handbook-index로 보유 연도·part를 확인한 뒤 검색 도구를 사용하세요. 지침·편람의 원본 적재·파싱도 데이터 파이프라인 저장소에서 수행합니다.

Cursor / Claude Desktop 연결

프로젝트 루트에서 pip install -e . 후 콘솔 스크립트 또는 패키지 모듈을 stdio MCP로 실행합니다.

Cursor — .cursor/mcp.json 또는 전역 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "open-ALIO-mcp": {
      "command": ".venv/Scripts/python.exe",
      "args": ["-m", "open_alio_mcp"],
      "cwd": "C:/path/to/open_alio_mcp"
    }
  }
}

macOS/Linux는 command를 .venv/bin/python으로, cwd를 실제 경로로 바꿉니다.

Claude Desktop — 배포 후에는 uvx 한 줄 구성을 권장합니다. 라이브 API 키가 필요하면 위 설치 섹션의 env 예시처럼 MCP 설정에 환경변수를 추가합니다.

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

로컬 체크아웃을 직접 연결할 때는 위 Cursor 예시와 같은 .venv Python 구성을 사용합니다.

연결 확인: AI에게 get_server_status 실행을 요청하거나, "ALIO 지표 카테고리 목록 보여줘"처럼 자연어로 질의합니다.

사용자별 활용법

아래 질문 예시는 AI가 적절한 tool을 자동 조합해 답변합니다.

일반 국민 — 채용·시설·기관 이해

공공기관 종사자 — 동종 비교·인력·공시 주기

유관 부서·공무원 — 정책·국감·법령·평가

데이터·연구 — 교차 분석·출처 검증

신뢰성 설계: 데이터가 없으면 추정하지 않고 결측으로 답하며, 공시 주기 기준으로 공백 사유를 안내합니다.

검증 현황 (Tool verification status)

핵심 도구는 tests/test_smoke.py(오프라인 기능·CI)와 scripts/security_smoke_test.py(입력 검증)로 스모크 테스트를 수행하며, 한국전력공사·LH·국립공원공단 등 대표 기관 시나리오를 포함합니다. 원천 데이터의 파싱·라이브 ALIO 대조 검증은 데이터 파이프라인 저장소에서 수행합니다.

도구별 상세 검증표·테스트 계획은 docs/testing.md 참조. fixture 기반 회귀 테스트와 CI 확대는 로드맵에 포함되어 있습니다.

폴더 구조

런타임 패키지 코드는 src/open_alio_mcp/ 아래에 있습니다.

데이터 수집·빌드 파이프라인(크롤러·파서·빌드 스크립트·원본 rawdata)은 별도 데이터 저장소에서 관리합니다.

데이터 출처·한계

• 모든 응답에 출처(source)와 유의사항(caveats)이 포함됩니다.
• 원천: 재정경제부 NKOD OpenAPI(공공데이터포털·ALIO Plus) + ALIO 항목별 공시 엑셀 + ALIO 공시 페이지 크롤링 + 네이버 뉴스 검색 API + 국가법령정보센터 Open API(법제처) + 사용자 투입 지침·경영평가편람 파일.
• 법령·행정규칙은 현행 기준 조회 결과이며 법률 자문이 아닙니다. 로컬 지침·편람은 파일 추출 텍스트라 표·서식이 손실될 수 있어 인용 시 원문 대조를 권장합니다.
• 뉴스 결과는 언론 보도이며 기관의 공식 입장·공시 정보가 아닙니다.
• 공시 수치 기준이며 기관 평가·정책 판단의 근거가 아닙니다.
• 금액 단위는 카테고리별로 다릅니다(천원/백만원) — 응답 unit 필드 확인.

데이터 카테고리별 출처·갱신주기·갱신 방법은 docs/data_sources.md 참조.

로드맵 (Roadmap)

상세 로드맵은 docs/roadmap.md 참조.

어려운 도메인 모델링 작업의 대부분은 이미 프로젝트에 구현되어 있으며, 남은 작업은 주로 패키징·테스트·데이터 갱신·배포 통제 같은 운영 보강입니다.

문서 (Documentation)

라이선스 (License)

MIT License