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 설계이므로, 출처 추적성이 중요한 공공부문 활용에 적합합니다.

Related MCP server: korean-law-alio-mcp

이 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 부분입니다. 예를 들어 hong@example.com이면 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 부분 (예: hong@gmail.com → 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