서울시 건설알림이 MCP

서울시 열린데이터광장의 건설공사(공사장) 정보를 자연어로 검색·조회할 수 있게 해주는 MCP(Model Context Protocol) 서버. Claude Desktop, Claude Code, Claude 웹(커넥터)에 연결하면 "서초구에 지금 진행 중인 공사 뭐 있어?" 같은 질문에 서울시 공식 데이터로 답할 수 있다.

상태

✅ 로컬 전용(stdio) 서버로 운영 중. 별도 클라우드 서버나 URL 접속이 없고, 인증키·사용량 제한도 없다. 각자 자기 컴퓨터에 이 저장소를 내려받아 Claude가 직접 실행하는 방식이다. (과거 fly.io로 웹 배포했던 버전은 2026-09에 완전히 폐쇄했다 — 더 이상 어떤 URL로도 서비스되지 않는다.)

Related MCP server: narajangteo-prespec

제공 도구 (4개)

모든 도구는 결과에 출처 필드(서울 열린데이터광장 데이터셋명)를 포함하며, 이 MCP로 얻은 정보를 답변에 쓸 때는 반드시 출처를 함께 밝혀야 한다.

사용하는 원본 데이터

• 서울시 건설알림이 사업개요 (OA-15585)

• 서울시 건설알림이 공사사진 (OA-15586)

• 서울시 건설 알림이 정보, ListConstructionWorkService (OA-1222)

• 서울시 건설공사 추진 현황, ListOnePMISBizInfo (OA-2540)

설치 방법 (비개발자용, 처음이어도 괜찮습니다)

준비물은 딱 두 가지입니다: Node.js와 서울 열린데이터광장 인증키(무료, 누구나 즉시 발급).

0단계 — 사전 준비

Node.js 설치 확인

이미 Claude Code나 다른 MCP를 써보셨다면 대부분 설치되어 있습니다. PowerShell (윈도우) 또는 터미널(맥)에서 아래 명령을 입력해보세요.

node --version

v18 이상 버전이 뜨면 통과입니다. "명령을 찾을 수 없다"는 에러가 뜨면 nodejs.org에서 LTS 버전을 내려받아 설치한 뒤 다시 시도하세요.

서울 열린데이터광장 인증키 발급

1. data.seoul.go.kr에서 회원가입/로그인

2. 인증키 신청 페이지에서 인증키 신청 (승인까지 보통 즉시~수 분)

3. 발급된 인증키(영문+숫자 조합 문자열)를 복사해둔다 — 아래 2단계에서 씀

1단계 — 이 저장소 내려받기

PowerShell(윈도우) 또는 터미널(맥)에서, 원하는 위치로 이동한 뒤:

git clone https://github.com/hlucent/seoul-construction-mcp.git
cd seoul-construction-mcp
npm install

git이 없다면 git-scm.com에서 설치하거나, GitHub 페이지 우측의 "Code → Download ZIP"으로 내려받아 압축을 풀어도 됩니다.

npm install 실행 후, 지금 폴더의 전체 경로를 메모해두세요. 다음 단계에서 그대로 씁니다. 확인 방법:

# 윈도우
echo %cd%

# 맥
pwd

2단계 — Claude에 등록하기

아래 세 가지 중 본인 환경에 맞는 방법 하나만 따라 하면 됩니다.

방법 A — Claude Desktop (가장 많이 씀)

1. Claude Desktop 실행 → 설정(Settings) → Developer → "Edit Config" 클릭 (또는 아래 파일을 직접 텍스트 편집기로 연다)

   • 윈도우 (일반 설치): %APPDATA%\Claude\claude_desktop_config.json

   • 윈도우 (Microsoft Store 설치): %LOCALAPPDATA%\Packages\Claude_<임의문자열>\LocalCache\Roaming\Claude\claude_desktop_config.json (탐색기 주소창에 %LOCALAPPDATA%\Packages를 붙여넣으면 Claude_로 시작하는 폴더를 찾을 수 있다. 일반 경로를 수정했는데 Claude가 계속 옛날 설정을 쓰는 것처럼 보인다면, Microsoft Store 버전이라 이 경로가 진짜일 가능성이 높다 — 실제로 이 프로젝트에서 겪었던 문제다.)

   • 맥: ~/Library/Application Support/Claude/claude_desktop_config.json

2. 파일 안 "mcpServers" 객체 안에 아래 항목을 추가한다. 이미 다른 MCP가 등록되어 있다면 그 옆에 콤마(,)로 이어붙인다. 경로(args)는 반드시 1단계에서 메모해둔 본인 폴더의 실제 경로로 바꿔야 한다.

   "seoul-construction-mcp": {
     "command": "node",
     "args": [
       "여기에_본인_경로/seoul-construction-mcp/src/index.js"
     ],
     "env": {
       "SEOUL_OPENAPI_KEY": "본인의_서울시_인증키"
     }
   }

   윈도우 경로는 \를 두 번(\\) 써야 합니다. 예: "C:\\Users\\내계정\\seoul-construction-mcp\\src\\index.js"

   연결이 자꾸 실패한다면? "command": "node" 대신 node.exe의 전체 경로를 직접 써보세요. PowerShell에서 (Get-Command node).Source로 확인할 수 있습니다 (보통 C:\\Program Files\\nodejs\\node.exe).

3. 파일 저장 → Claude Desktop을 완전히 종료했다가 다시 실행한다. (창을 닫는 것만으로는 부족할 수 있다. 작업표시줄 트레이 아이콘에서 종료하거나, 윈도우는 PowerShell에서 Get-Process | Where-Object { $_.ProcessName -like "*Claude*" } | Stop-Process -Force로 완전히 끈 뒤 재실행하면 확실하다.)

4. 새 대화창을 열어 "서초구 진행 중인 공사 알려줘"처럼 물어보고 확인한다.

방법 B — Claude Code (CLI를 이미 쓰고 있다면)

터미널에서 프로젝트 폴더 어디서든 아래 한 줄로 등록할 수 있습니다.

claude mcp add seoul-construction-mcp -s user -- node 본인_경로/seoul-construction-mcp/src/index.js

인증키는 실행할 때 환경변수로 넘기거나, 위 방법 A의 env 방식처럼 .mcp.json에 직접 넣어도 됩니다. 자세한 옵션은 claude mcp add --help 참고.

방법 C — Claude 웹(claude.ai) 커넥터로 쓰고 싶다면

claude.ai의 커넥터는 기본적으로 URL(원격 서버) 연결만 지원하고, 이 프로젝트처럼 내 컴퓨터에서 직접 실행하는 stdio 방식은 등록할 수 없습니다. 웹에서 쓰고 싶다면 별도로 웹 서버로 배포해야 하는데(예: Fly.io 등), 이 저장소는 현재 로컬 전용 구조라 별도 작업이 필요합니다. 개인/사무실 용도로는 방법 A(Desktop)나 B(Code)를 권장합니다.

3단계 — Claude Code로 설치 자체를 대신 시키기 (제일 쉬운 방법)

위 단계가 복잡하게 느껴진다면, 이 저장소를 내려받은 뒤(1단계까지만) Claude Code를 열고 이렇게 요청하세요.

CLAUDE.md 읽고, 이 프로젝트를 Claude Desktop에 등록하는 것까지 도와줘.
내 서울시 인증키는 [여기에 붙여넣기]야.

Claude Code가 본인 컴퓨터의 실제 경로를 확인하고, 설정 파일 위치를 찾아서 (Microsoft Store 버전인지도 자동으로 확인), 등록까지 대신 진행해준다.

문제 해결

개발/기여용 참고

이 저장소를 직접 수정하고 싶다면 CLAUDE.md(작업 원칙)와 DEVLOG.md(개발 일지)를 참고하세요. 서버 코드는 src/index.js 한 파일이며, MCP SDK의 StdioServerTransport를 사용하는 순수 stdio 서버입니다(웹 서버, 인증, 사용량 제한 로직 없음).

로컬에서 코드를 고친 뒤 직접 동작을 확인하려면:

cp .env.example .env
# .env를 열어 SEOUL_OPENAPI_KEY 값을 채운다
npm start