occ-gis-mcp

Oklahoma Corporation Commission(오클라호마 기업위원회)의 공개 데이터 허브에서 공개 GIS 데이터셋에 접근할 수 있는 기능을 AI 어시스턴트(Claude, GitHub Copilot 또는 MCP 호환 클라이언트)에게 제공하는 MCP(Model Context Protocol) 서버입니다: https://gisdata-occokc.opendata.arcgis.com/

설정에 코딩 경험이 필요하지 않습니다. 아래 단계를 순서대로 따르세요.

쉽게 설명하면 무엇인가요?

MCP("Model Context Protocol")는 AI 채팅 도구가 실시간 데이터를 가져오는 작은 프로그램("서버")을 호출할 수 있게 하는 표준 방식입니다. 이 저장소는 바로 그러한 서버 중 하나입니다. 설정이 완료되면 AI 어시스턴트에게 다음과 같은 질문을 할 수 있습니다:

• "OCC GIS 허브에서 사용 가능한 데이터셋 목록을 보여줘"

• "Oklahoma County의 모든 활성 유정을 찾아줘"

• "PST Tanks 레이어에서 사용 가능한 필드를 보여줘"

그러면 어시스턴트는 이 서버를 사용하여 추측하는 대신 실제 실시간 답변을 가져옵니다.

Related MCP server: mcp-arcgis-houston

1단계 — Node.js 설치

이 서버는 Node.js에서 실행됩니다. 아직 설치하지 않았다면:

1. https://nodejs.org로 이동합니다.

2. 운영 체제에 맞는 LTS(Long Term Support) 버전을 다운로드합니다.

3. 설치 프로그램을 실행하고 기본값을 수락합니다.

4. 터미널(Windows에서는 PowerShell, Mac/Linux에서는 Terminal)을 열고 다음을 실행하여 설치가 완료되었는지 확인합니다:

   node -v
   npm -v

   둘 다 버전 번호(예: v20.11.0)를 출력해야 합니다. 오류가 표시되면 터미널/컴퓨터를 다시 시작하고 다시 시도하세요.

2단계 — 이 프로젝트 다운로드

옵션 A: Git 사용(이미 설치되어 있다면 권장)

git clone https://github.com/MSPFE2019/occ-gis-mcp.git
cd occ-gis-mcp

옵션 B: Git 없이

1. https://github.com/MSPFE2019/occ-gis-mcp로 이동합니다.

2. 초록색 Code 버튼 → Download ZIP을 클릭합니다.

3. 기억할 수 있는 위치(예: 내 문서 폴더)에 압축을 풉니다.

4. 터미널을 열고 압축을 푼 폴더로 cd합니다. 예:

   cd "C:\Users\YourName\Documents\occ-gis-mcp"

3단계 — 의존성 설치

프로젝트 폴더 안에서 다음을 실행합니다:

npm install

이 명령은 서버에 필요한 작은 라이브러리들을 다운로드합니다. 이 작업은 한 번만 하면 됩니다(코드가 변경될 때마다 다시 실행).

4단계 — 실행 테스트

이 서버를 실행하는 방법은 두 가지가 있으며, 사용할 환경에 따라 선택하세요:

• index.js — 로컬 데스크톱 도구(Claude Desktop, VS Code/Copilot Chat)용.

• http.js — Copilot Studio 같은 원격/클라우드 도구용(아래 전용 섹션 참조).

먼저 로컬 버전을 시도해 보세요:

node index.js

아무것도 출력되지 않을 것입니다 — 정상입니다! MCP 서버는 조용한 입출력 채널을 통해 통신하며 클라이언트가 연결하기를 기다릴 뿐입니다. 중지하려면 Ctrl+C를 누르세요.

더 시각적인 테스트를 위해 공식 MCP Inspector를 사용할 수 있습니다. 이 도구는 버튼을 클릭하고 실시간 결과를 볼 수 있는 브라우저 페이지를 엽니다:

npx @modelcontextprotocol/inspector node index.js

로컬 웹페이지가 열립니다. Connect를 클릭한 다음 List Tools를 클릭하고, 인수 없이 list_datasets를 실행해 보세요 — 실제 데이터셋 목록이 JSON으로 반환되는 것을 볼 수 있습니다. 이렇게 작동한다면 서버가 올바르게 작동하는 것입니다.

5단계 — AI 어시스턴트에 연결

MCP 서버는 AI 클라이언트의 설정에서 한 번 구성됩니다. 사용 중인 도구에 맞는 가이드를 선택하세요:

Claude Desktop

1. Claude Desktop → Settings → Developer → Edit Config를 엽니다(텍스트 편집기에서 claude_desktop_config.json이 열립니다).

2. 다음과 같은 항목을 추가합니다(경로를 실제 프로젝트 폴더로 바꾸고, Windows에서는 이중 백슬래시 \\를 사용하세요):

   {
     "mcpServers": {
       "occ-gis": {
         "command": "node",
         "args": ["C:\\Users\\YourName\\Documents\\occ-gis-mcp\\index.js"]
       }
     }
   }

3. 파일을 저장하고 Claude Desktop을 완전히 다시 시작합니다.

4. "어떤 OCC GIS 데이터셋을 사용할 수 있나요?"라고 물어보세요.

VS Code(GitHub Copilot Chat) 또는 기타 MCP 인식 편집기

1. MCP 설정에서 mcp.json 파일을 열거나 생성합니다(VS Code: 명령 팔레트 → "MCP: Open User Configuration", 또는 작업 공간의 .vscode/mcp.json에 추가).

2. 위에 표시된 것과 동일한 mcpServers 블록을 추가합니다.

3. 창을 다시 로드하면 Copilot과 채팅할 때 새 도구가 나타납니다.

기타 MCP 클라이언트

MCP 표준을 지원하는 모든 클라이언트는 동일한 형태의 구성을 수락합니다: command(node)와 args(index.js의 전체 경로). 구성 파일이 있는 위치는 클라이언트의 문서를 참조하세요.

사용 가능한 도구

연결되면 어시스턴트가 다음을 호출할 수 있습니다:

다른 ArcGIS Hub 사이트로 사용자 지정

이 서버는 OCC 데이터에만 국한되지 않습니다 — DCAT-US 카탈로그 피드를 노출하는 모든 ArcGIS Hub 사이트(대부분의 공개 ArcGIS Hub 사이트가 해당)에서 작동합니다. 다른 사이트를 지정하려면 server.js를 열고 상단 근처의 다음 줄을 변경하세요:

const HUB_BASE = "https://gisdata-occokc.opendata.arcgis.com";

대상 사이트의 기본 URL로 바꾼 다음 서버를 다시 실행하세요. 다른 모든 것(도구 이름, 쿼리 로직)은 동일하게 작동합니다.

Microsoft Copilot Studio에 연결

Copilot Studio는 이 서버를 직접 실행하지 않습니다 — HTTPS URL로 인터넷을 통해 접근해야 합니다. 이것이 index.js(로컬 도구 전용)와 달리 http.js가 존재하는 이유입니다. 두 부분으로 구성됩니다: (A) 서버를 인터넷에서 접근 가능한 곳에 배포한 다음, (B) Copilot Studio에 등록합니다.

A. HTTP 서버를 공개 위치에 배포

가장 쉬운 방법을 선택하세요 — 모두 동일한 명령을 실행합니다: npm install 후 npm run start:http.

초보자에게 가장 쉬운 방법 — Azure App Service(또는 Azure Container Apps)

1. 이 저장소를 자신의 GitHub 계정으로 푸시합니다(포크/복사본에서 이 글을 읽고 있다면 이미 완료된 상태입니다).

2. Azure Portal에서 Web App을 생성합니다 → 런타임 스택: Node 20 LTS → GitHub 저장소에서 배포합니다(Azure가 CI/CD를 자동 설정합니다).

3. Configuration → Startup Command에서 다음을 설정합니다:

   node http.js

4. 배포가 완료되면 Azure가 https://occ-gis-mcp.azurewebsites.net 같은 URL을 제공합니다. MCP 엔드포인트는 해당 URL에 /mcp를 붙인 것입니다. 예: https://occ-gis-mcp.azurewebsites.net/mcp.

또한 간단한 방법 — Render, Railway 또는 Fly.io 이 중 어느 것이든 GitHub의 Node.js 저장소를 몇 번의 클릭으로 배포할 수 있습니다:

• 빌드 명령: npm install

• 시작 명령: npm run start:http

• 공개 https://... URL을 제공합니다 — 역시 /mcp를 추가하세요.

로컬 테스트 전용(프로덕션용 아님)

npm install
npm run start:http

이 명령은 http://localhost:3000/mcp에서 서버를 시작합니다. Copilot Studio(클라우드 서비스)가 자신의 컴퓨터에 있는 서버에 연결할 수 있는지 테스트하려면 ngrok(ngrok http 3000) 같은 터널 도구가 필요하며, 이 도구는 임시 공개 HTTPS URL을 제공합니다. 빠른 데모에는 적합하지만 실제/지속적인 사용에는 적합하지 않습니다.

B. Copilot Studio에 등록

1. Copilot Studio에서 에이전트를 열고 → Tools(또는 Actions) → Add a tool → New tool → Model Context Protocol로 이동합니다.

2. 이름(예: "OCC GIS Data")을 지정하고 서버의 HTTPS URL을 /mcp를 포함하여 붙여넣습니다. 예: https://occ-gis-mcp.azurewebsites.net/mcp.

3. No authentication(이 서버는 읽기 전용이며 자격 증명이 필요하지 않음)을 선택합니다. 자체 인증 계층을 앞에 추가한 경우는 예외입니다.

4. 저장합니다. Copilot Studio가 서버를 호출하고 네 가지 도구(list_datasets, get_dataset, get_layer_metadata, query_layer)와 해당 설명을 자동으로 검색합니다 — 수동 스키마 입력이 필요 없습니다.

5. Copilot Studio 테스트 채팅 창에서 테스트합니다: "어떤 OCC GIS 데이터셋을 사용할 수 있나요?" 또는 "Oklahoma County의 활성 유정을 찾아줘"라고 물어보세요.

사용 가능한 도구

연결되면 어시스턴트가 다음을 호출할 수 있습니다:

문제 해결

• node: command not found — Node.js가 설치되지 않았거나 설치 후 터미널을 다시 시작해야 합니다. 1단계를 다시 수행하세요.

• 네트워크/fetch 관련 Inspector/도구 호출 오류 — 인터넷 연결을 확인하세요. 서버는 모든 요청에서 실시간 ArcGIS Hub API를 호출합니다.

• 어시스턴트가 새 도구를 인식하지 못함 — 파일 경로(로컬) 또는 URL(Copilot Studio)이 올바른지, 클라이언트를 완전히 다시 시작했거나 다시 연결했는지 확인하세요.

• Copilot Studio가 연결할 수 없다고 표시 — /mcp로 끝나는 URL(도메인만이 아닌)을 등록했는지, 배포가 실제로 실행 중인지, 일반 HTTPS로 접근 가능한지(VPN/방화벽 차단 없이) 확인하세요.

참고 사항

• 데이터셋 목록은 허브의 DCAT-US 카탈로그 피드에서 실시간으로 가져오며 속도 유지를 위해 15분간 캐시됩니다.

• 데이터는 공개이지만 소스 기관의 이용 약관(get_dataset 출력의 라이선스 필드에 표시됨)이 적용됩니다.

• http.js는 무상태 모드(요청당 새 서버)로 실행되므로 호스팅이 간단하며 Copilot Studio가 MCP 도구를 호출하는 방식과 완전히 호환됩니다.