sinmb79/KCSC-MCP

KCSC MCP Server

국가건설기준(KCS/KDS)을 AI 대화 안에서 바로 검색하고 읽습니다

소개

KCSC MCP Server는 국가건설기준센터(KCSC) OpenAPI를 MCP 서버로 감싸서, Claude Desktop/Claude Code/Codex 등 AI 클라이언트 안에서 KCS(건설기준)와 KDS(설계기준)를 바로 검색하고, 본문을 읽고, 특정 조항을 찾을 수 있게 합니다.

브라우저를 열고, 키워드를 바꾸고, 페이지를 넘기는 대신 -- AI에게 물어보세요.

이런 분들에게 유용합니다

제공 도구

빠른 시작 가이드

1단계: 설치

git clone https://github.com/sinmb79/KCSC-MCP.git
cd KCSC-MCP

python -m venv.venv

# Windows:.venv\Scripts\activate
# macOS/Linux:
source.venv/bin/activate

# 설치
pip install -e ".[dev]"

2단계: API 키 설정

KCSC API 키를 https://www.kcsc.re.kr/support/api에서 발급받으세요.

# Windows:
copy.env.example.env
# macOS/Linux:
cp.env.example.env

.env 파일을 편집합니다:

KCSC_API_KEY=your_real_kcsc_api_key

3단계: 서버 실행

# 방법 1: Python 직접 실행
python server.py

# 방법 2: 설치된 스크립트
kcsc-mcp

4단계: AI 클라이언트 연결

Claude Desktop

%AppData%\Claude\claudedesktopconfig.json (Windows):

{
  "mcpServers": {
    "kcsc": {
      "command": "D:/Workspace/KCSC-MCP/.venv/Scripts/python.exe",
      "args": ["D:/Workspace/KCSC-MCP/server.py"],
      "env": {
        "KCSC_API_KEY": "your_kcsc_api_key"
      }
    }
  }
}

Claude Code

claude mcp add --transport stdio kcsc -- python server.py

Codex

codex mcp add kcsc -- python server.py

실전 사용 예시

추천 사용 흐름

가장 효율적인 순서입니다. 처음부터 본문을 열지 마세요.

1. kcsc_search_codes  -->  관련 문서 후보 찾기
2. kcsc_list_codes    -->  범위 좁히기 (필요 시)
3. kcsc_search_sections --> 문서 내부에서 필요한 조항 확인
4. kcsc_get_content   -->  전체 문맥 읽기

예시 1: 콘크리트 관련 기준 찾기

AI에게 이렇게 말하세요:

콘크리트 관련 KCS 기준을 찾아줘

AI가 호출하는 도구:

kcsc_search_codes(keyword="콘크리트", code_type="KCS")

결과 예시:

[
  {"code": "114010", "fullCode": "2010114010", "codeName": "콘크리트 공사 일반"},
  {"code": "114020", "fullCode": "2010114020", "codeName": "콘크리트 배합"},
  {"code": "114030", "fullCode": "2010114030", "codeName": "콘크리트 타설"}
]

예시 2: 문서 내부 조항 검색

콘크리트 공사 일반 기준에서 거푸집 관련 내용을 찾아줘

kcsc_search_sections(code_type="KCS", code="114010", keyword="거푸집", limit=5)

문서 전체를 읽지 않고도, 해당 키워드가 등장하는 제목과 본문 단락만 빠르게 확인할 수 있습니다.

예시 3: 기준 문서 본문 조회

KCS 114010 전문을 보여줘

kcsc_get_content(code_type="KCS", code="114010", plain_text=True)

plain_text=True로 설정하면 HTML 태그가 제거된 깨끗한 텍스트를 받습니다.

예시 4: 도로 설계기준 목록 조회

도로 관련 KDS 기준 목록을 보여줘

kcsc_list_codes(code_type="KDS", keyword="도로", limit=20)

code와 fullCode

KCSC API 응답에는 code(6자리)와 fullCode(10자리)가 함께 나옵니다:

이 서버에서는 둘 다 입력으로 받을 수 있습니다. 내부적으로 적절한 코드로 변환하여 API를 호출합니다.

캐시

반복 호출을 줄이기 위해 메모리 캐시를 사용합니다.

# 캐시 TTL 조정 (초)
KCSC_CACHE_TTL_SECONDS=600

SSL/네트워크 설정

일부 Windows/사내망 환경에서 SSL 인증서 문제가 발생할 수 있습니다.

검증 우선순위:

프로젝트 구조

KCSC-MCP/
|-- server.py          # MCP 서버 (4개 도구)
|-- pyproject.toml     # 프로젝트 메타데이터
|-- requirements.txt   # 의존성
|--.env.example       # 환경변수 템플릿
+-- tests/
    +-- test_server.py # 테스트

테스트 실행

pytest

테스트 항목: 코드 타입 검증, HTML 제거, 오류 정규화, 섹션 검색, 캐시 불변성

환경 변수 목록

자주 묻는 질문

API 키를 넣었는데 동작하지 않아요

• 키 만료 여부 확인
• .env 파일이 프로젝트 루트에 있는지 확인
• Claude Desktop 설정의 env에도 키를 넣었는지 확인

SSL 인증서 오류가 나요

• 먼저 기본 설정으로 재시도
• 사내망이면 KCSCCABUNDLE에 사내 CA 번들 지정
• 최후 수단으로만 KCSCVERIFYSSL=false 사용

code와 fullCode가 헷갈려요

• 둘 다 입력 가능합니다. 서버가 자동으로 변환합니다.

라이선스

MIT License -- 자유롭게 사용, 수정, 배포할 수 있습니다.

만든 사람

22B Labs (sinmb79) -- The 4th Path

문의사항이나 기여는 Issues를 이용해 주세요.