KCSC MCP Server

국가건설기준(KCS/KDS)을 AI 대화 안에서 바로 검색하고 읽습니다 Search and read Korean Construction Standards (KCS/KDS) directly within AI conversations

---

소개 | Introduction

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

KCSC MCP Server wraps the Korean Construction Standard Center (KCSC) OpenAPI as an MCP server, enabling AI clients like Claude Desktop, Claude Code, and Codex to search, read, and navigate KCS (Construction Standards) and KDS (Design Standards) documents directly.

브라우저를 열고, 키워드를 바꾸고, 페이지를 넘기는 대신 -- AI에게 물어보세요. Instead of opening a browser, changing keywords, and flipping pages -- just ask your AI.

---

이런 분들에게 유용합니다 | Who Is This For?

대상	활용 예시
건설 엔지니어	설계 검토 중 KDS 기준 조항을 즉시 확인
시공 관리자	KCS 시공 기준 본문을 AI 대화 안에서 바로 조회
건축사/감리원	관련 기준 문서를 키워드로 빠르게 검색
공무원	사업 기획 시 적용 기준 확인
학생/연구자	건설기준 학습 및 조항 검색

Who	Use Case
Civil engineers	Instantly check KDS design standard clauses during review
Construction managers	Query KCS construction standards within AI conversations
Architects / Supervisors	Search related standard documents by keyword
Government officials	Verify applicable standards during project planning
Students & researchers	Study and search construction standard clauses

---

제공 도구 | Available Tools

#	도구 Tool	설명 Description
1	kcsc_list_codes	KCS/KDS 코드 목록 조회 (타입, 키워드, 페이지네이션) / List codes with filtering
2	kcsc_search_codes	코드명 기반 빠른 검색 / Quick search by code name
3	kcsc_get_content	특정 문서 전체 본문 조회 (HTML 제거 옵션) / Get full document content
4	kcsc_search_sections	문서 내부 제목/본문 키워드 검색 / Search sections within a document

---

빠른 시작 가이드 | Quick Start Guide

1단계: 설치 | Step 1: Install

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

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

2단계: API 키 설정 | Step 2: Configure API Key

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

Get your API key from 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단계: 서버 실행 | Step 3: Start Server

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

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

4단계: AI 클라이언트 연결 | Step 4: Connect AI Client

Claude Desktop

%AppData%\Claude\claude_desktop_config.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

---

실전 사용 예시 | Real-World Usage Examples

추천 사용 흐름 | Recommended Workflow

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

The most efficient order. Don't open full content first.

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

예시 1: 콘크리트 관련 기준 찾기 | Example 1: Find Concrete Standards

AI에게 이렇게 말하세요 | Say this:

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

AI가 호출하는 도구 | Tool called:

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

결과 예시 | Example result:

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

예시 2: 문서 내부 조항 검색 | Example 2: Search Within a Document

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

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

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

예시 3: 기준 문서 본문 조회 | Example 3: Read Full Document

KCS 114010 전문을 보여줘

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

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

예시 4: 도로 설계기준 목록 조회 | Example 4: List Road Design Standards

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

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

---

code와 fullCode | About code vs fullCode

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

필드	예시	설명
code	114010	문서 본문 조회에 사용하는 6자리 코드
fullCode	2010114010	목록에서 보이는 10자리 전체 코드

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

Both code and fullCode are accepted as input. The server normalizes them internally.

---

캐시 | Caching

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

항목 Item	설명 Description
코드 목록	전체 코드 목록 캐시
문서 본문	문서별 본문 캐시
기본 TTL	600초 (10분)

# 캐시 TTL 조정 (초) | Adjust cache TTL (seconds)
KCSC_CACHE_TTL_SECONDS=600

---

SSL/네트워크 설정 | SSL/Network Configuration

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

SSL certificate issues may occur in some Windows/corporate network environments.

검증 우선순위 | Verification priority:

순위	방법	설정
1 (권장)	기본 설정 그대로	(설정 불필요)
2	사내 CA 번들 지정	KCSC_CA_BUNDLE=C:\certs\corp-ca.pem
3 (비권장)	SSL 검증 비활성화	KCSC_VERIFY_SSL=false

---

프로젝트 구조 | Project Structure

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

---

테스트 실행 | Running Tests

pytest

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

---

환경 변수 목록 | Environment Variables

변수 Variable	필수	설명 Description
KCSC_API_KEY	필수	KCSC OpenAPI 키
KCSC_CACHE_TTL_SECONDS	선택	캐시 TTL (기본: 600초)
KCSC_CA_BUNDLE	선택	사내 CA 인증서 번들 경로
KCSC_VERIFY_SSL	선택	SSL 검증 비활성화 (false)

---

자주 묻는 질문 | FAQ

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

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

SSL 인증서 오류가 나요

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

code와 fullCode가 헷갈려요

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

---

라이선스 | License

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

MIT License -- Free to use, modify, and distribute.

---

만든 사람 | Author

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

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

For questions or contributions, please use Issues.