geo-figure-mcp — 지리 시험용 지도·그래프 만들기 (0.2.6)

만든 사람: 김한솔 (한백고등학교 지리 교사)

AI에게 "서울 자치구 주간 인구 지수 지도랑 산점도, 구 이름은 A~E로 숨겨서"처럼 말하면, 실제 통계를 찾아 흑백 시험지용 지도·그래프를 만들어 줍니다. 결과는 PPTX·HWPX 파일이고, 지역 한 칸·막대 하나·글자 하나까지 도형으로 들어갑니다(그림 파일이 아닙니다). 그룹 해제(개체 풀기)를 한 번만 하면 하나씩 고칠 수 있습니다.

무엇이 되나

지도: 한국 시·도 / 시·군·구(2026년 판, 16개 시·도), 세계·대륙(위·경도선과 숫자 눈금, graticule: 0으로 숨김), 단계 구분도(빗금·회색), A~E 기호, 지점, 흐름 화살표, 축척 자동, 경계 단순화 3단계
지형: 등고선 지형도·지형 단면(실제 표고), 교과서식 모식도 7종(암석 해안, 모래 해안·석호, 하안 단구, 카르스트, 화산, 빙하, 식생의 수직 분포)
그래프: 막대·누적 막대, 산점도·버블, 기후 그래프, 편차, 인구 피라미드, 삼각 그래프
통계(실제 자료만, 숫자를 지어내지 않음)
- 세계은행 WDI, Our World in Data(에너지·CO2): 인증키 없음
- 기후: WMO 1991~~2020 평년값 관측소 4,697곳 내장 + 평가원 기후 기출 지점 67곳(2022~~2026학년도)
- 내장 KOSIS 통계 17종(인증키 없이 사용): 인구 구조(부양비·노령화 지수·중위 연령), 성·5세 연령별 인구(피라미드), 인구주택총조사, 주간 인구 지수(2020), 외국인 주민 유형, 합계 출산율(10년), 시·도 간 인구 이동, 도시 지역 인구, GRDP, 제조업 업종별 출하액, 산업별 사업체, 최종 에너지 소비, 신재생 에너지, 농가 인구, 노지 채소·시설 작물·작물별 재배 면적 — scripts/build-kosis.js 로 다시 받을 수 있음
- 시·도별 발전원별 발전량(공공데이터포털, 이용 허락 '제한 없음')
  - 원자력: 2014~2025년, 호기별 발전량을 발전소 소재 시·도로 합침
  - 석탄·LNG·유류: 2018~2021년, 전력시장 거래량
  - 태양광: 2025년
- 시·도별 발전원별 발전 설비 용량(KOSIS, 한국전력거래소, 2021~2025년)
- 에너지경제연구원 『지역에너지통계연보』는 이용약관상 무단 복제·제공이 금지라 넣지 않았습니다. 검산에만 썼습니다(원자력 2021년 값 일치).
- KOSIS 직접 조회(위에 없는 통계): 각자 무료 인증키 필요
- 서울 자치구 주간 인구(2020 인구주택총조사) 내장
출제 가공: 최댓값=100 지수·비율·편차·반올림, 지역명 → A~~E/(가)~~(마)(무작위·북→남·서→동), 판별이 잘 되는 지역 추천
시험지 규칙(교사 인터뷰 + 경기도교육청 「지리」 평가 문항 제작 자료)
- 흑백 구분
- 출처는 그림 오른쪽 아래
- 확대 지도엔 축척
- 정답표는 파일 마지막 장
만들기 전에 AI가 계획(지표·연도·지역·가공·기호 순서·출력)을 요약해 보여 주고 확인을 받습니다(확인 없이는 파일을 만들지 않음).
시안 먼저: 파일을 만들기 전에 대화창에 미리보기 그림을 보여 줍니다. 지도 기호 모양은 4가지(① 흰 테두리 ② 바탕 없음 ③ 네모 흰 바탕 ④ 작은 원 흰 바탕)를 나란히 보여 주고 고르게 합니다.
필요한 정보만 조회: 내장 통계는 list_bundled_data의 query로 검색하고 summary:true로 키와 주제만 볼 수 있습니다. 로컬 시안의 previewId가 있으면, 교사가 확인한 뒤 같은 그림 명세 대신 ID를 보내 파일을 만들 수 있습니다(최대 30분).
만든 뒤 고치기: 그림과 함께 설계도(<이름>.geo-figure.json)를 저장합니다. "범례 바꿔 줘", "화성시 빼 줘", "기호 순서 바꿔 줘"라고 하면 통계를 다시 찾지 않고 그 부분만 고쳐 다시 만듭니다.
자동 업데이트: 설정에 geo-figure-mcp@latest 를 쓰면 앱을 켤 때마다 최신 버전을 받습니다. 예전 버전이 돌고 있으면 AI가 "새 버전이 있다"고 알려 줍니다.

설치 (Claude 데스크톱)

Node.js 20 이상(LTS) 설치 — 이것만 있으면 됩니다. 프로그램은 처음 쓸 때 자동으로 내려받습니다(npx).
(소스로 고쳐 쓰고 싶을 때만) 이 폴더에서 npm install 후 "command": "node", "args": ["C:/경로/geo-figure-mcp/src/server.js"]
Claude 데스크톱 → 설정 → 개발자 → 구성 편집 → claude_desktop_config.json 에 추가:

{
  "mcpServers": {
    "geo-figure": {
      "command": "npx",
      "args": ["-y", "geo-figure-mcp@latest"],
      "env": { "GEO_FIGURE_OUT": "C:/Users/<이름>/Documents/지리시험자료" }
    }
  }
}

Claude 데스크톱을 다시 켜고 "지리 시험 자료 만들어 줘"라고 말합니다.
(선택) 내장 자료에 없는 KOSIS 통계를 직접 받고 싶을 때만:
- KOSIS 공유서비스에서 인증키를 무료로 발급받습니다.
- Claude에게 "KOSIS 키 저장해 줘: ○○○"라고 말하면 이 컴퓨터 사용자 폴더에만 저장됩니다.

설치 (Google Antigravity)

Node.js 설치는 위와 같습니다.
Antigravity → 에이전트 창의 … → MCP Servers → Manage MCP Servers → View raw config 를 열거나, 아래 파일을 직접 엽니다.
- 전체 공통: C:/Users/<이름>/.gemini/config/mcp_config.json (예전 판: .gemini/antigravity/mcp_config.json)
다음을 넣고 저장합니다(경로는 / 로).

{
  "mcpServers": {
    "geo-figure": {
      "command": "npx",
      "args": ["-y", "geo-figure-mcp@latest"],
      "env": { "GEO_FIGURE_OUT": "C:/Users/<이름>/Documents/지리시험자료" }
    }
  }
}

MCP 목록에서 새로 고침 → geo-figure 도구 14개가 보이면 됩니다. 에이전트에게 "geo-figure 로 경기도 주간 인구 지수 지도 만들어 줘"라고 말합니다.

npx 를 못 찾는다고 나오면 command 에 C:/Program Files/nodejs/npx.cmd 처럼 전체 경로를 넣습니다.
원격 서버를 쓸 때는 "serverUrl": "https://…/mcp?token=비밀번호" 한 줄로 등록합니다(url·httpUrl 이 아님).

내장 통계와 지도 이름 맞추기

지도와 그래프에 필요한 항목은 bundle.items, 지역은 bundle.regions(정확한 mapName 또는 통계표 지역명)로 고릅니다. 한 시·도의 지도용 시·군·구를 모두 받으려면 bundle.within을 씁니다. 예를 들어 find_data에 {"source":"bundle","bundle":{"key":"daytime-population","period":"2020","items":["주간 인구 지수"],"within":["경기"]}}를 보내면 경기도 시·군의 해당 지수만 받습니다.
내장 자료의 각 행에는 mapName(예: '경기 화성시')이 붙어 있어 지도 기호·단계 구분에 그대로 씁니다.
일반구(수원시 장안구 등)는 지도에서 시로 합쳐 그리므로 mapName 이 없고, 시 합계 행을 씁니다.
지도 판은 자료 연도에 맞춥니다. 2026년 7월 이전 자료는 2025년 판(17개 시·도)을 씁니다. 결과의 mapEdition 을 지도 edition 에 넣으면 됩니다.
단계 구분에 지도에 없는 이름이 섞이면 조용히 빠지지 않고 오류로 알립니다.
그림 명세는 guide(topic:"spec", section:"map")처럼 지도·그래프·지형 중 필요한 부분만 볼 수 있습니다(map, chart, terrain). 기출 기후 지점은 summary:true로 이름과 기후 기호만, 기후 통계는 indicators:["temp"] 또는 ["precip"]로 필요한 값만 조회할 수 있습니다. 지도 지역명은 list_regions에 query와 edition을 지정해 확인합니다.

선생님들은 어떻게 쓰나 — 두 가지 방법

	① 내 컴퓨터에 설치 (권장)	② 원격 서버 주소 붙이기
쓰는 AI	Claude 데스크톱 (MCP를 지원하는 데스크톱 앱)	ChatGPT·Claude 웹·Gemini 등
준비	Node.js 설치 + 설정 파일 한 줄 (위 '설치')	주소와 비밀번호만 받으면 끝
그림 파일	내 컴퓨터에만 저장	서버에서 한 번 내려받음(받으면 바로 지움)
정답표	파일 마지막 장에 들어감	파일에 넣지 않음 — 대화창에만 보여 줌
KOSIS 직접 조회	내 키로 가능	안 됨 (내장 통계만)
알맞은 용도	내신 시험 문항	연수 체험, 수업·연습 자료

①은 선생님마다 각자 자기 컴퓨터에서 돌리는 방식이라 서버가 필요 없고, 남의 서버를 거치지 않습니다. 대화 내용은 쓰는 AI 회사로 가니, 학생 개인정보는 대화에 넣지 마세요.

원격 서버 (ChatGPT·Gemini·Claude 웹)

설치 없이 주소만 붙여 쓰게 하려면 서버 한 곳에 올립니다.

이 폴더를 깃허브에 올리고, Render 같은 곳에서 'Docker 웹 서비스'로 연결합니다. render.yaml·Dockerfile 이 들어 있습니다.
받은 주소를 환경 변수 PUBLIC_URL 에 넣습니다(예: https://geo-figure-mcp.onrender.com). ACCESS_TOKEN(접속 비밀번호)은 필수입니다 — Render는 무작위로 만들어 줍니다.
각 AI에 MCP 주소 https://…/mcp?token=비밀번호 를 붙입니다.
- ChatGPT: 설정 → 커넥터(개발자 모드) → 새 커넥터 → 주소 입력
- Claude 웹: 설정 → 커넥터 → 사용자 지정 커넥터 추가
- Gemini CLI: settings.json 의 mcpServers 에 httpUrl 로 추가

보안·사용량 규칙

정답표는 파일에 넣지 않습니다. 내려받기 주소가 새도 정답은 새지 않게 하려는 것입니다.
만든 파일은 한 번 받으면 바로 지우고, 안 받아도 60분 뒤 지웁니다(KEEP_MINUTES).
서버에는 KOSIS 키가 없고, 원격에서는 KOSIS 직접 조회를 끕니다(키를 대화창에 붙여 넣지 않도록). 내장 통계만 씁니다.
학교 양식 글꼴은 저장하지 않으니 make_figures 의 style 로 매번 넘깁니다.
사용량 제한: IP마다 전체 MCP 요청 1분 60회, 파일 생성 1시간 90회, 서버 전체 파일 생성 하루 600회(DAILY_MAX). 이름·학교 같은 개인정보는 받지 않고, IP는 사용량 계산에만 메모리에 잠깐 둡니다.
카드가 등록된 곳(Cloud Run 등)에 올리면 예산 알림과 최대 인스턴스 수를 꼭 정하세요.
내 컴퓨터에서 시험: ACCESS_TOKEN=아무거나 npm run start:remote → node examples/remote-test.js http://localhost:8787/mcp 아무거나

고치는 법

PowerPoint: 그림 선택 → 마우스 오른쪽 → 그룹 → 그룹 해제 한 번. 시·군·구, 경계선, 범례, 막대가 모두 따로 움직입니다.
- 기호(A, (가) 등)는 글자와 흰 테두리가 함께 움직이도록 작은 묶음 하나로 남습니다. 글자를 바꾸려면 그것만 한 번 더 풀면 됩니다.
- 도형 이름이 지역 이름입니다(홈 → 정렬 → 선택 창에서 "경기 화성시"처럼 보임).
- 단계를 손으로 바꿀 땐 범례 칸을 고르고 서식 복사(붓)로 지역에 칠하면 됩니다.
한글: 그림 선택 → 마우스 오른쪽 → 개체 풀기 한 번. 조각이 제자리에 남습니다.
- 그림이 쪽에 다 안 들어가면 제목부터 다음 쪽으로 넘어갑니다(겹치지 않음).
범례·기호만 바꾸기: 로컬에서 preview_figures에 saved: {name, legend, labelStyle}처럼 파일 이름과 바꿀 내용만 보냅니다. labels에는 기호를 바꿀 기존 지도 지역만 적습니다. 그림이나 지도가 여러 개라면 figure와 part로 대상을 지정할 수 있습니다(1부터). 수정 시안을 확인한 후 make_figures에 previewId, 새 이름, 출력 형식을 보냅니다. 지도 기호를 바꿨다면 그래프 기호와 정답표를 확인합니다.
크게 바꿀 땐 AI에게 말로: 설계도를 읽어 그 부분만 바꿔 다시 만듭니다(open_figure_spec).
글꼴
- 한글 파일은 함초롬돋움(한글 기본 글꼴), PowerPoint 파일은 맑은 고딕(한국어 윈도 기본)을 씁니다.
- "그림 글꼴을 ○○로 바꿔 줘"라고 하면 다음부터 그 설정으로 만듭니다(set_style).

기후 자료 출처 (지점마다 결과에 표시)

기출 지점 67곳은 계산한 쾨펜 기후를 평가원 기호와 대조했습니다(node scripts/check-koppen.js).

지점 수	출처	기준
48곳	WMO 1991~2020 평년값	관측소 50km 이내
7곳	NOAA GHCN-Daily 일별 기록	그달 20일 이상 기록된 해 10년 이상으로 직접 평균
11곳	Beck et al.(2023) 0.1° 격자 1991~2020	관측소 자료가 부족한 곳만. 격자 추정값이라고 표시함

대조 결과 62곳은 일치했습니다. 다른 5곳은 경계형이나 고산 기후입니다(밴쿠버, 튀니스, 산티아고, 아디스아바바, 보고타).
칭다오는 평년값 계산(Cwa)에 따라 Cw로 정정했습니다.
티베트고원은 고원 중앙의 WMO 퉈퉈허(沱沱河) 관측소(해발 4,535m, 최난월 8.4℃ → ET)를 대표 지점으로 씁니다.

예시와 검사

node examples/run.js → examples/out/ 에 예시 5개를 만듭니다.
1. 시·도 발전
2. 서울 주간 인구
3. 세계 기후 기출 지점
4. 울릉도 등고선·단면
5. 지형 모식도
node examples/mcp-test.js → MCP 서버를 실제로 띄워 주요 도구를 불러 봅니다.
npm test → 자동 검사(그림 종류별 생성, PPTX·HWPX 구조, 묶음 한 겹, 미리보기, 내장 자료). 깃허브에서 push와 배포 때마다 돕니다.

자료와 라이선스

코드: MIT
한국 경계: 본 데이터는 통계청 통계지리정보서비스(SGIS, https://sgis.kostat.go.kr)에서 공공누리 제1유형으로 개방한 행정동 경계를 가공한 것이며(가공: vuski/admdongkor, https://github.com/vuski/admdongkor), CC BY 4.0으로 배포됩니다. 이 도구는 이를 시·군·구로 합치고 단순화했습니다. 지도를 넣으면 그림 출처에 자동으로 표시됩니다.
세계 경계: Natural Earth(퍼블릭 도메인), topojson/world-atlas 가공(ISC License, Copyright Mike Bostock)
기후
- WMO Member Nations (2023). WMO Climatological Standard Normals for 1991-2020 (NCEI Accession 0253808). NOAA NCEI. https://doi.org/10.25921/800j-vn07 — 이용 제한 없음, 인용 표시
- NOAA GHCN-Daily(미국 정부 자료, 이용 제한 없음)
- Beck, H.E. et al. (2023) 쾨펜-가이거 기후 분류 1km 지도(CC BY 4.0, doi:10.6084/m9.figshare.21789074)
- 평가원 기출 기후 지점 목록: 지명·기후 기호·출제 시험 날짜만 정리한 사실 목록(교사 정리, skyblue3925-svg/geo-lab). 문항 원문·그림은 들어 있지 않습니다.
표고: Terrain Tiles(AWS 공개 데이터, 원자료 SRTM·GMTED·ETOPO1 등) — 쓸 때 내려받아 출처를 자동 표시
통계
- 내장 KOSIS 통계: 국가데이터처(통계청) 등 작성기관 자료, KOSIS(공공누리 제1유형, 출처 표시). 표마다 출처가 자료에 들어 있습니다.
- 발전원별 발전량: 공공데이터포털 한국전력거래소·한국수력원자력 파일 데이터(이용 허락 범위 제한 없음)
- 세계은행 WDI(CC BY 4.0), Our World in Data(CC BY 4.0) — 쓸 때 받아 옴
시험지 규칙: 교사 인터뷰와 경기도교육청 「지리」 평가 문항 제작 자료를 참고해 다시 쓴 규칙입니다(원문 수록 안 함).
WorldClim 등 재배포가 금지된 자료와 교과서·시험 문항 원문은 넣지 않았습니다.
자료의 정확성은 원자료를 따릅니다. 시험에 쓰기 전에 수치와 경계를 한 번 더 확인하세요.

geo-figure-mcp

Documentation