NetLogo를 위한 최초의 MCP (Model Context Protocol) 서버 — AI 어시스턴트가 자연스러운 대화를 통해 에이전트 기반 모델 (Agent-Based Models)을 생성, 실행 및 분석할 수 있도록 지원합니다.

호환 도구: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (Copilot), Cline, Continue, Roo Code, Zed, OpenCode, Codex — MCP를 지원하는 모든 도구.

에이전트 기반 모델링 (Agent-Based Modeling) 과정을 수강 중인 AI 학생으로서, NetLogo를 제어할 MCP 서버를 찾아보았지만 — 존재하는 것이 없었습니다. 그래서 직접 만들었습니다.

NetLogo 코드를 수동으로 작성하고, 버튼을 클릭하고, 슬라이더를 조정하는 대신, AI 어시스턴트에게 원하는 내용을 평이한 영어(plain English)로 말하면 됩니다:

"양 100마리와 늑대 20마리가 있는 포식자-피식자 모델을 만들어줘. 500 틱 (ticks) 동안 실행하고 인구 역학 (population dynamics)을 보여줘."

AI가 코드를 작성하고, 시뮬레이션을 실행하며, 결과를 보여줍니다 — 이 모든 과정이 대화를 통해 이루어집니다.

기본적으로 (처음 사용 시) 실제 NetLogo 창이 열리므로 시뮬레이션이 실행되는 모습을 실시간으로 볼 수 있습니다. CI 또는 서버를 위한 헤드리스 모드 (Headless mode)도 사용할 수 있습니다.

코드로 모델 생성— 슬라이더, 스위치, 버튼, 모니터와 같은 실제 인터페이스 위젯(widgets) 포함
시뮬레이션 실행— 마크다운 표 (markdown tables) 형태로 틱 단위 (tick-by-tick) 데이터 수집
BehaviorSpace 실험 실행— 헤드리스 런처 (headless launcher)를 통한 병렬 파라미터 스윕 (parameter sweeps)
뷰를 PNG로 내보내기— 채팅창 내에 인라인으로 표시 가능
모든 요소 검사— 월드 상태 (world state), 에이전트 샘플, 히트맵을 위한 패치 그리드 (patch grids)
CoMSES Net 통합— 가장 큰 피어 리뷰(peer-reviewed) ABM 라이브러리에서 모델을 검색하고 안전하게 실행
내장 참조 자료— NetLogo 프리미티브 (primitives), 프로그래밍 가이드, 6→7 전환 가이드를 MCP 리소스 (resources)로 제공
지연 시작 (Lazy startup)— AI 클라이언트가 연결될 때가 아니라, 실제로 도구를 사용할 때만 NetLogo 창이 열림

25개 도구 전체 레퍼런스, 위젯 스키마 (widget schema) 및 프롬프트 (prompts)는 docs/TOOLS.md를 참조하세요.

요구 사항	터미널을 통한 설치 가능 여부?	방법
Python 3.10+	예	Windows: winget install Python.Python.3.12 · macOS: brew install python@3.12 · Linux: sudo apt install python3.12
Java JDK 11+	예	Windows: winget install EclipseAdoptium.Temurin.21.JDK · macOS: brew install --cask temurin · Linux: sudo apt install openjdk-21-jdk
NetLogo 7.0+	아니요 — 수동 설치	ccl.northwestern.edu/netlogo에서 다운로드

NetLogo만 수동 다운로드가 필요합니다. 그 외의 모든 항목은 터미널을 통해 설치할 수 있으며, 아래의 Zero-Config Setup (무설정 설정) 프롬프트가 이를 자동으로 처리합니다.

AI 코딩 도구를 사용 중이라면, 아래 프롬프트를 채팅창에 복사하세요. AI가 사용자의 OS를 감지하고, 설치된 NetLogo 및 Java를 찾아 리포지토리 (repo)를 클론(clone)하고, 의존성 (dependencies)을 설치하며, MCP 클라이언트 (client)를 구성한 뒤 사용 방법을 안내할 것입니다.

설정 프롬프트 복사하기

NetLogo MCP 서버를 처음부터 끝까지 설정해 주세요. 다음 단계를 주의 깊게 따라주세요:
1. **내 환경 감지**
- 내 OS (Windows / macOS / Linux)를 식별합니다.
...

pip install netlogo-mcp

그 다음 MCP 클라이언트에 서버를 추가하세요. Claude Code의 경우, 프로젝트의 .mcp.json에 추가합니다:

{
"mcpServers": {
"netlogo": {
...

Claude Code를 재시작하고 /mcp로 확인하세요.

팁: 글로벌 설정 (global config)보다는 프로젝트 범위 설정 (project-scope config, 한 프로젝트 내의 .mcp.json)을 권장합니다. 글로벌 항목은 모든 프로젝트의 모든 세션에서 서버를 로드하기 때문입니다.

Cursor, Windsurf, VS Code, Cline, Continue, Roo Code, Zed, OpenCode, Codex 또는 Claude Desktop을 사용 중인가요? 11개 클라이언트 모두에 대한 정확한 설정 방법은 docs/CLIENTS.md를 참조하세요. 모든 설정 옵션 (GUI/headless 모드, 디렉토리, 제한 사항)은 docs/CONFIGURATION.md에 있습니다.

개발 또는 기여를 원하시나요? 리포지토리를 클론하고 대신 편집 가능 모드 (editable)로 설치하세요:

git clone https://github.com/Razee4315/NetLogo-MCP.git
cd NetLogo-MCP
pip install -e ".[dev]"

이미지에는 번들된 JRE와 함께 NetLogo (headless)가 포함되어 있어, 호스트 설치가 필요하지 않습니다:

docker build -t netlogo-mcp .
docker run -i --rm netlogo-mcp

MCP 클라이언트 설정 (MCP client config):

{
"mcpServers": {
"netlogo": {
...

Docker는 headless 모드로만 실행됩니다 (GUI 모드 없음). 내보낸 뷰(views)와 월드(worlds)를 호스트에 유지하려면 -v ./exports:/data/exports를 추가하세요.

연결이 완료되면, 모든 MCP 클라이언트에서 다음 프롬프트(prompts)를 시도해 보세요:

> 50마리의 거북이(turtles)가 무작위 보행(random walk)을 하는 간단한 NetLogo 모델을 생성해줘.
setup을 실행하고, 100 틱(ticks) 동안 시뮬레이션한 뒤, 뷰를 내보내줘.
> Wolf Sheep Predation 모델을 열고 파라미터 스윕(parameter sweep)을 실행해줘.
...

첫 번째 모델 도구 호출(model tool call)은 JVM이 시작되는 동안 30~60초가 소요됩니다 — NetLogo 창은 준비가 되면 나타납니다. '중지(stop)'를 클릭하지 마세요. 그 이후의 모든 호출은 즉각적으로 이루어집니다.

문제	해결 방법
NETLOGO_HOME is not set	환경 변수를 NetLogo 설치 디렉토리로 설정하세요
JAVA_HOME is not set	JDK 디렉토리(JRE 아님)로 설정하세요
시작 시 JVM 충돌	JAVA_HOME이 이전 버전이 아닌 JDK 11 이상을 가리키고 있는지 확인하세요
No model is loaded	다른 도구를 사용하기 전에 open_model 또는 create_model을 호출하세요
첫 모델 호출 시 30~60초 동안 멈춤	정상입니다 — JVM이 예열(warming up) 중입니다. '중지'를 클릭하지 마세요.
AI 클라이언트를 시작할 때 NetLogo 창이 열림	NETLOGO_EAGER_START=true로 설정되어 있거나 이전 버전을 사용 중입니다 — 기본적으로 창은 첫 번째 도구 사용 시에만 열립니다
서버가 연결되지 않음	터미널에서 netlogo-mcp를 수동으로 실행하여 에러 출력을 확인하세요

• docs/TOOLS.md — 전체 도구 참조, 위젯 스키마(widget schema), BehaviorSpace 및 CoMSES 가이드
• docs/CONFIGURATION.md — 모든 환경 변수, GUI vs headless, 시작 타이밍
• docs/SECURITY.md — 보안 모델(security model) 및 신뢰 경계(trust boundary)
• docs/CLIENTS.md — 11개 모든 MCP 클라이언트에 대한 설정
• docs/DEVELOPMENT.md — 프로젝트 구조, 테스트 실행, 아키텍처 노트
• CONTRIBUTING.md — 기여 방법
• CHANGELOG.md — 버전 기록

연구나 교육에 NetLogo MCP를 사용하신다면, 인용(cite)해 주세요 — GitHub 사이드바의 **"Cite this repository"**를 클릭하거나 CITATION.cff를 참조하세요.

Saqlain Abbas
Email: saqlainrazee@gmail.com
GitHub: @Razee4315
LinkedIn: @saqlainrazee

이 프로젝트는 MIT 라이선스 (MIT License) 하에 라이선스가 부여됩니다 — 어떤 목적으로든 자유롭게 사용, 수정 및 배포할 수 있습니다.