PortDock MCP(portdock-mcp.exe)는 AI 클라이언트가 띄우는 창 없는 서버입니다. MCP(Model Context Protocol)는 AI 클라이언트가 바깥 프로그램의 «도구» 를 부르는 약속이고, 이 서버를 붙이면 AI 가 대화 중에 이 PC 의 COM 포트 목록·Port Inspector 보고서·랜카드를 읽고, 사용자가 알려 준 장비에서 Modbus·MC 프로토콜·SCPI 값을 읽습니다. 0.7.0 부터 릴리스에 들어 있어 지금 받아 쓸 수 있습니다.
할 수 있는 것과 없는 것
| 도구 | 하는 일 |
|---|---|
| ports_list · port_inspect | COM 포트 목록, 포트 하나의 드라이버·문제 코드·USB 경로·절전·지연 타이머(읽기만) |
| serial_read | 포트를 열어 최대 10초 듣기 — 보내지 않음 |
| modbus_read | FC 01~04 읽기 한 번(TCP·RTU·RTU over TCP) |
| mc_read | MC 3E 이진 일괄 읽기(0401) |
| scpi_query | «?» 로 끝나는 질의 하나 — *RST·*TST?·*CAL? 등 거절 |
| ping · net_adapters | 핑(최대 10번), 랜카드 설정·절전·방화벽 프로필 |
| device_map_get | 내장 장비 레지스터 맵 |
| modbus_write_sim · mc_write_sim | 127.0.0.1·localhost 의 시뮬레이터에만 쓰기 |
쓰기 도구 두 개는 이 PC 주소(127.0.0.1·::1·localhost)만 받고, 다른 주소는 연결하기 전에 거절합니다. 판정은 주소로만 합니다 — 이 PC 에서 다른 장비로 넘겨 주는 프로그램(TCP 중계·게이트웨이·SSH 터널 등)을 띄워 두면 127.0.0.1 로 쓴 값이 실제 장비까지 갈 수 있으니, 그런 프로그램이 떠 있을 때는 쓰기 도구를 쓰지 않습니다. 모든 호출은 이 PC 의 세션 기록(%LOCALAPPDATA%\dev.portdock\mcp-log, 휴대 폴더가 있으면 그 안)에 남고 밖으로 보내지 않습니다. 같은 대상은 100ms 에 한 번, 전체는 1분에 120번까지입니다.
1. 설치
- Claude Desktop: 릴리스의 PortDock-MCP.mcpb 를 내려받아 열면 설치 화면이 나옵니다. 오류 문구 언어(en·ko)를 고를 수 있습니다.
- 그 밖의 클라이언트: PortDock-MCP.zip 을 원하는 폴더(예: C:\Tools\PortDock-MCP)에 풀고, 아래처럼 command 에 exe 경로를 넣습니다. 인자는 없습니다.
- Scoop 을 쓴다면: scoop bucket add portdock https://github.com/portdock/scoop-bucket 을 한 번 한 뒤 scoop install portdock/portdock-mcp. 설치된 폴더는 scoop prefix portdock-mcp 로 확인하고, 설정의 command 에 그 안의 portdock-mcp.exe 경로를 넣습니다.
- 코드 서명이 아직 없어 회사 PC 에서는 보안 정책이 실행을 막을 수 있습니다. 그때는 관리자에게 먼저 묻습니다.
2. 설정 예시
Claude Desktop 을 손으로 설정할 때는 «설정 → 개발자 → 설정 편집» 으로 여는 claude_desktop_config.json 에 넣고 앱을 다시 시작합니다. Cursor 의 mcp.json 도 같은 모양입니다.
{
"mcpServers": {
"portdock": {
"command": "C:\\Tools\\PortDock-MCP\\portdock-mcp.exe",
"env": { "PORTDOCK_MCP_LANG": "ko" }
}
}
}VS Code 는 작업 폴더의 .vscode/mcp.json 에 servers 로 적습니다.
{
"servers": {
"portdock": {
"type": "stdio",
"command": "C:\\Tools\\PortDock-MCP\\portdock-mcp.exe"
}
}
}Claude Code 는 명령줄에서 한 번 등록합니다.
claude mcp add portdock -- C:\Tools\PortDock-MCP\portdock-mcp.exe
JSON 안의 경로는 역슬래시를 두 번(\\) 씁니다. 붙인 뒤 클라이언트의 도구 목록에 ports_list 등 11개가 보이면 됩니다. 도구를 부를 때마다 클라이언트가 허락을 묻는 화면은 끄지 않고 두는 것을 권합니다.
3. 실장비 없이 연습 — PLC Simulator
- PortDock PLC Simulator 를 열고 프레임 3E·이진, 묶을 주소 127.0.0.1, 포트 5000(기본) 그대로 «시작». D100~D102 에 값을 넣어 둡니다.
- AI 에게: «127.0.0.1 포트 5000 의 PLC 시뮬레이터에서 D100 부터 3워드 읽어 줘» → mc_read 가 불리고 값이 돌아옵니다.
- «D200 에 42 를 쓰고 다시 읽어서 확인해 줘» → mc_write_sim 다음 mc_read. 시뮬레이터 화면의 D200 도 바뀝니다.
- 같은 말에서 주소만 192.168.0.10 처럼 바꾸면 mc_write_sim 은 «Refused» 로 끝납니다 — 이 PC 가 아닌 주소에는 연결하지 않습니다.
4. Modbus Slave 로 연습
- PortDock Modbus Slave 에서 연결 방식 «TCP 서버(Modbus TCP)» 를 고르고, 묶을 주소를 127.0.0.1 로 바꾸고(기본 0.0.0.0 은 다른 PC 도 붙을 수 있고 방화벽 창이 뜹니다) 빈 포트(예: 1502)로 시작한 뒤 보유 레지스터 몇 칸에 값을 넣습니다.
- «127.0.0.1:1502 국번 1 에서 보유 레지스터 0 부터 4개 읽어 줘» → modbus_read(FC 03). «0~1 을 float(ABCD)로 풀어 줘» 처럼 풀이도 시킬 수 있습니다.
- 장비 맵을 쓰려면 «오토닉스 MT4W 레지스터 맵에서 측정값 주소 알려 줘» → device_map_get. 주소·배율은 비공식 자료이므로 장비 매뉴얼로 한 번 더 봅니다.
5. COM 포트 문제를 같이 보기
«COM 포트 목록 보여 줘», «COM3 의 드라이버와 USB 절전 설정 읽어 줘», «COM3 이 최근 7일 동안 언제 끊겼는지 봐 줘» 처럼 물으면 ports_list·port_inspect 가 불립니다. 결과에서 사용자 폴더 경로는 «~», MAC 주소는 «xx-…» 로 가려집니다. 고칠 곳(장치 관리자·전원 옵션)은 사람이 바꿉니다 — 이 서버는 설정을 바꾸지 않습니다.
주의
- 도구 결과는 사용 중인 AI 클라이언트로 넘어갑니다. 회사 장비 값을 다룬다면 그 클라이언트의 데이터 정책을 먼저 확인합니다.
- 쓰기 도구는 주소만 봅니다. 이 PC 에서 실제 장비로 넘겨 주는 프로그램(PortDock TCP 의 중계, 벤더 게이트웨이, SSH 터널 등)을 띄운 채 쓰기 도구를 쓰지 않습니다.
- 장비가 보낸 글(예: *IDN? 응답)은 데이터일 뿐입니다. 서버도 클라이언트에게 그렇게 알립니다.
- AI 가 읽은 값의 뜻을 단정하지 않게, 단위·배율·주소 표기(40001 등)는 장비 매뉴얼로 맞춰 봅니다.
근거
- Model Context Protocol — Connect to local MCP servers — Claude Desktop 설정 파일(mcpServers·command·env)
- VS Code — Use MCP servers — .vscode/mcp.json 의 servers·type stdio
- Cursor — Model Context Protocol — mcp.json 의 mcpServers
- MCP Bundles (.mcpb) — 묶음 형식(manifest.json)
작성 2026-10-30