JOURNAL / ENTRY
cokacremote 분석: ChatGPT가 리눅스 서버를 직접 다루게 해주는 20개의 MCP 도구
~/cokacremote의 실제 TypeScript 소스를 분석해 20개 MCP 도구, 프로세스 관리, 파일 편집, OAuth 인증, 배포 구조와 테스트 결과를 정리했다.
최근 AI 에이전트를 실제 개발 서버와 연결해서 사용하는 방법에 관심이 많아졌다. 단순히 코드를 제안하는 수준을 넘어, AI가 서버에서 명령을 실행하고 파일을 수정하고 서비스를 재시작하는 단계까지 가려면 어떤 연결 계층이 필요할까?
이번에는 내 서버의 ~/cokacremote 프로젝트를 실제 소스 코드 기준으로 살펴봤다. 결론부터 말하면 cokacremote는 VPS나 EC2 같은 리눅스 서버를 ChatGPT 등 MCP 클라이언트가 원격 개발 환경처럼 사용할 수 있게 만드는 Full-access MCP 서버다.
현재 버전은 0.1.0이며 Node.js + TypeScript로 작성되어 있다. 핵심 의존성은 다음과 같다.
Node.js >= 22
MCP SDK @modelcontextprotocol/sdk 1.30.0
Express 5.2.1
Zod 4.4.3
TypeScript 7.0.2
Vitest 4.1.11
가장 중요한 특징은 샌드박스형 도구가 아니라는 점이다. cokacremote 프로세스가 가진 운영체제 권한으로 호스트의 셸, 파일 시스템, 네트워크를 그대로 사용할 수 있다. 강력한 대신 인증과 배포 보안이 매우 중요하다.
1. cokacremote는 무엇을 하는 프로그램인가?
구조를 아주 단순하게 표현하면 다음과 같다.
ChatGPT / MCP Client
│
│ MCP Streamable HTTP
▼
cokacremote
│
├── Shell / Process
├── File System
├── Git / Build / Test
├── Package Manager
└── systemd / Docker / Nginx 등
│
▼
Linux Host
일반적인 챗봇은 "이 명령을 실행하세요"라고 알려주는 데서 끝난다. 반면 cokacremote가 연결되어 있으면 AI가 다음과 같은 작업을 직접 수행할 수 있다.
pwd,ls,df,free같은 시스템 점검- npm/pip/apt 패키지 설치
- Git clone, pull, branch 작업
- Node.js/Python 프로젝트 빌드와 테스트
- Docker / Docker Compose 실행
- systemd 서비스 상태 확인과 재시작
- Nginx 설정 확인과 수정
- 파일 생성, 읽기, 편집, 이동, 삭제
- 장시간 실행되는 프로세스의 출력 추적
- 대화형 프로세스에 stdin 전달
즉 원격 서버의 터미널과 파일 작업을 MCP 도구로 구조화한 것에 가깝다.
2. 제공되는 MCP 도구는 총 20개
소스의 src/exec-tools.ts와 src/file-tools.ts를 직접 확인하면 정확히 20개 도구가 등록되어 있다.
크게 두 그룹으로 나뉜다.
실행 / 프로세스 관리 : 6개
파일 시스템 관리 : 14개
--------------------------
총 : 20개
실행 및 프로세스 도구 6개
| 도구 | 역할 |
|---|---|
exec_command | 셸 명령 실행 |
run_script | Bash, sh, Node.js, Python 등의 전체 스크립트 실행 |
write_stdin | 실행 중인 프로세스에 입력 전달 |
read_process | 장기 실행 프로세스의 새로운 출력 조회 |
terminate_process | 실행 중인 프로세스 종료 |
list_processes | 실행 중 또는 최근 완료된 프로세스 목록 조회 |
파일 시스템 도구 14개
| 도구 | 역할 |
|---|---|
list_directory | 디렉터리 목록 조회 |
stat_path | 파일·폴더·심볼릭 링크 메타데이터 조회 |
read_file | UTF-8 또는 base64로 파일 읽기 |
write_file | 파일 생성·덮어쓰기·이어쓰기 |
replace_in_file | 파일 안의 특정 문자열을 정확하게 교체 |
apply_patch | unified diff 패치 적용 |
upload_file | base64 청크 방식 파일 업로드 |
download_file | base64 청크 방식 파일 다운로드 |
make_directory | 디렉터리 생성 |
copy_path | 파일 또는 디렉터리 복사 |
move_path | 이동 또는 이름 변경 |
remove_path | 파일 또는 디렉터리 영구 삭제 |
chmod_path | Unix 파일 권한 변경 |
hash_file | SHA-256, SHA-512, MD5 해시 계산 |
이제 중요한 도구들을 조금 더 자세히 살펴보자.
3. 가장 강력한 도구: exec_command
exec_command는 사실상 cokacremote의 핵심이다.
MCP 요청으로 다음과 비슷한 명령을 보낼 수 있다.
pwd
node --version
docker compose ps
npm test
sudo systemctl status nginx
내부적으로 Node.js의 spawn()을 사용하며, 기본적으로 로그인 셸의 -lc 방식으로 명령을 실행한다.
특히 중요한 점은 실행 환경이다.
MCP 서버 프로세스의 OS 권한
+ 환경변수
+ 파일 시스템 접근권한
+ 네트워크 접근권한
을 그대로 상속한다.
따라서 단순 명령뿐만 아니라 다음과 같은 전체 개발 흐름도 가능하다.
Git clone
↓
npm install
↓
소스 수정
↓
npm test
↓
npm run build
↓
Docker 재배포
↓
Nginx / Health Check
AI에게 서버 작업을 시킬 때 가장 자주 사용하는 도구가 이 exec_command다.
4. 복잡한 작업은 run_script
한두 줄 명령이 아니라 여러 단계의 로직이 필요하면 run_script가 더 편리하다.
지원 runtime은 다음과 같다.
bash
sh
node
python
custom
예를 들어 Python 데이터 정리 프로그램이나 긴 Bash 배포 스크립트를 통째로 전달할 수 있다.
cokacremote는 전달받은 스크립트를 /tmp 아래 임시 디렉터리에 파일로 만든 뒤 실행한다. 기본적으로 실행이 끝나면 임시 스크립트는 삭제되며, 필요하면 keepScript=true로 남길 수도 있다.
custom runtime을 이용하면 특정 인터프리터도 지정할 수 있기 때문에 사실상 확장성이 높다.
5. 장시간 작업도 끊기지 않는 프로세스 관리
원격 MCP에서 특히 중요한 부분이 장시간 실행 작업이다.
예를 들어 다음 명령은 바로 끝나지 않을 수 있다.
npm install
npm run build
docker compose build
pytest
cokacremote는 이런 작업을 프로세스 세션으로 관리한다.
exec_command가 일정 시간 안에 끝나지 않으면 UUID 형태의 sessionId를 반환한다. 이후 이 ID를 이용해 작업을 계속 추적한다.
exec_command
│
├── 즉시 완료 → 결과 반환
│
└── 계속 실행 → sessionId 반환
│
┌──────────┼──────────┐
▼ ▼ ▼
read_process write_stdin terminate_process
read_process
새롭게 출력된 stdout/stderr만 이어서 읽는다.
afterSeq와 nextSeq라는 커서를 사용하기 때문에 이전 로그를 매번 다시 받을 필요가 없다.
write_stdin
대화형 명령이나 실행 중인 프로그램에 문자열을 전달할 수 있다.
terminate_process
지원 신호는 다음과 같다.
SIGINT
SIGTERM
SIGKILL
기본 SIGTERM 종료 후 지정된 grace time 안에 프로세스가 끝나지 않으면 SIGKILL로 강제 종료할 수 있다.
또한 Linux에서는 자식 프로세스 하나만 죽이는 대신 프로세스 그룹 전체에 signal을 전달하도록 구현되어 있다. 빌드 도구처럼 자식 프로세스를 여러 개 만드는 프로그램에서 유용하다.
6. 파일을 직접 다룰 수 있는 14개 도구
cokacremote가 단순 SSH 명령 실행기와 다른 점 중 하나는 파일 조작이 개별 MCP Tool로 정리되어 있다는 것이다.
예를 들어 AI가 소스 코드를 수정할 때 무조건 sed나 Python 스크립트를 만들 필요가 없다.
read_file
파일 전체를 한 번에 읽는 대신 offset과 maxBytes 기반의 청크 방식으로 읽을 수 있다.
지원 형식은 다음 두 가지다.
utf8
base64
UTF-8 모드에서는 한글이나 이모지 같은 다중 바이트 문자를 청크 중간에서 잘라버리지 않도록 별도 처리가 되어 있다. 유효하지 않은 UTF-8 파일은 억지로 텍스트로 변환하지 않고 base64 사용을 요구한다.
write_file
UTF-8 텍스트뿐 아니라 base64 데이터도 저장할 수 있다.
overwrite
append
두 가지 모드를 지원하며 부모 디렉터리 자동 생성과 Unix file mode 설정도 가능하다.
replace_in_file
코드 수정에 꽤 유용한 도구다.
기본값에서는 교체할 문자열이 정확히 한 번 존재해야만 수정한다. 같은 문자열이 여러 곳에 있는데 애매하게 하나를 바꿔버리는 실수를 막는 장치다.
필요하면 expectedOccurrences로 예상 개수를 명시할 수도 있다.
7. 코드 수정에 유용한 apply_patch
apply_patch는 표준 unified diff를 이용해 파일을 수정한다.
내부적으로는 다음 계열의 명령을 사용한다.
git apply --unsafe-paths --whitespace=nowarn
세 가지 중요한 옵션도 지원한다.
checkOnly : 실제 반영 전에 적용 가능한지 검사
reverse : 패치를 역방향으로 적용
threeWay : git apply --3way 사용
여러 파일을 동시에 수정하는 개발 작업에서는 replace_in_file보다 patch 방식이 더 적합할 때가 많다.
단, 이름 그대로 --unsafe-paths가 활성화되어 있어 작업 디렉터리 밖의 경로까지 영향을 줄 수 있다. 이 서버가 제한된 코드 편집 도구가 아니라 Full-access 개발 도구라는 점을 다시 보여준다.
8. 대용량 파일은 업로드·다운로드 청크 방식
upload_file과 download_file은 base64 청크를 이용한다.
0 byte 1 MB 2 MB 3 MB
│------------│----------│----------│
chunk 1 chunk 2 chunk 3
각 호출에서 nextOffset을 받아 다음 청크를 이어서 전송한다.
업로드 시에는 각 청크에 대해 SHA-256 값도 계산해준다. 전체 파일의 검증은 hash_file로 할 수 있다.
hash_file은 다음 알고리즘을 지원한다.
sha256
sha512
md5
서버와 클라이언트 사이에서 파일을 전송한 후 동일한 파일인지 검사할 때 편리하다.
9. 경로 제한이 없다
파일 도구의 경로 형식은 세 가지를 모두 받아들인다.
상대경로
~/...
절대경로 /...
상대경로는 MCP_DEFAULT_CWD 기준으로 계산된다.
하지만 별도의 workspace jail이나 sandbox가 존재하는 것은 아니다. MCP 프로세스의 계정이 읽고 쓸 수 있는 경로라면 접근할 수 있다.
예를 들어 서비스가 높은 권한으로 실행된다면 시스템 설정까지 변경할 수 있다.
이것은 매우 편리하지만 동시에 cokacremote에서 가장 중요한 보안 특성이기도 하다.
10. 인증: Bearer Token + OAuth 2.1
Full-access 서버이기 때문에 인증이 핵심이다.
기본적으로 정적 Bearer Token 인증을 지원한다.
Authorization: Bearer <token>
토큰 비교에는 Node.js의 timingSafeEqual()을 사용한다.
ChatGPT 같은 MCP 클라이언트를 위한 OAuth 기능도 자체 구현되어 있다.
지원하는 주요 요소는 다음과 같다.
- OAuth 2.1 스타일 Authorization Code flow
- PKCE S256
- Dynamic Client Registration(DCR)
- access token
- rotating refresh token
- token revocation
- MCP
resource검증 mcp:toolsscope 검증
관련 엔드포인트는 다음과 같다.
/.well-known/oauth-protected-resource
/.well-known/oauth-authorization-server
/register
/authorize
/token
/revoke
OAuth가 활성화된 상태에서는 access token의 만료시간뿐 아니라 대상 resource와 mcp:tools scope까지 검사한다.
Host Header를 허용 목록과 비교하는 검증 기능도 있다.
11. MCP 전송 방식은 Stateless HTTP
cokacremote의 /mcp 엔드포인트는 Streamable HTTP를 사용하지만 요청별 stateless JSON 방식으로 구성되어 있다.
POST /mcp → 정상 MCP 요청
GET /mcp → 405
DELETE /mcp → 405
MCP HTTP 세션을 오래 유지하지 않는 대신, 실제 셸 프로세스 상태는 별도의 ProcessManager가 메모리에서 관리한다.
따라서 두 종류의 상태를 구분해야 한다.
MCP transport session ≠ process sessionId
HTTP 요청은 stateless여도 exec_command로 시작한 작업은 sessionId를 이용해 다음 요청에서 계속 조회할 수 있다.
12. 출력 폭주를 막기 위한 제한도 있다
명령이 엄청난 양의 로그를 출력한다고 해서 메모리를 무한정 사용하는 구조는 아니다.
기본 설정을 보면 다음과 같은 제한이 있다.
한 번의 응답 최대 출력 1 MB
프로세스당 보존 출력 4 MB
파일 청크 1 MB
replace 편집 대상 기본 최대 64 MB
관리 프로세스 최대 128개
완료 프로세스 보존 시간 1시간
HTTP 요청 body 8 MB
프로세스 출력은 내부적으로 16KB 청크로 관리된다. 보존 한도를 넘어가면 오래된 로그부터 버리고 droppedOutputBytes로 그 양을 알려준다.
장기 실행 에이전트에서 꽤 중요한 설계다.
13. 서버 배포 구조
프로젝트에는 systemd와 Nginx 예제도 포함되어 있다.
일반적인 운영 구조는 다음과 같다.
Internet
│
HTTPS :443
▼
Nginx
│
127.0.0.1:3000
▼
cokacremote
│
Linux Host
Nginx에서는 /mcp, OAuth 경로, /health를 Node.js 서비스로 reverse proxy한다.
긴 작업이 프록시에서 중간에 끊기지 않도록 MCP 경로의 read/send timeout을 길게 잡는 예제도 제공한다.
서비스는 systemd에서 자동 재시작하도록 구성할 수 있다.
14. 실제 테스트 결과
소스 분석만 하고 끝내지 않고 프로젝트 자체 테스트도 실행했다.
npm run typecheck
npm test
npm run build
결과는 다음과 같았다.
Test Files 6 passed / 6
Tests 22 passed / 22
Typecheck passed
Build passed
테스트 범위에는 단순 유닛 테스트뿐 아니라 실제 MCP Streamable HTTP 클라이언트를 이용한 통합 테스트도 포함된다.
테스트에서 검증하는 대표 항목은 다음과 같다.
- 20개 도구의 정확한 등록 목록
- Bearer 인증 성공/실패
- OAuth discovery, PKCE, refresh, revoke
- stateless MCP 요청
- 프로세스 실행 및 출력 polling
- stdin 전달
- timeout과 process termination
- UTF-8 청크 경계
- base64 검사
- 파일 권한
- 복사·이동·삭제 충돌 처리
- unified diff check/apply/reverse/3-way
- 파일 업로드·다운로드와 hash 검증
현재 실행 중인 서비스의 /health도 정상 응답하는 것을 확인했다.
15. 어떤 작업에 특히 유용할까?
cokacremote의 장점은 특정 개발 언어에 묶여 있지 않다는 것이다.
예를 들어 다음과 같은 작업에 잘 맞는다.
웹 서비스 개발
React / Next.js
Node.js / TypeScript
Python / FastAPI
Docker Compose
Nginx
MySQL / PostgreSQL
AI가 코드를 수정한 뒤 테스트하고 직접 서비스까지 재배포할 수 있다.
서버 관리
디스크 / 메모리 확인
systemd 서비스 관리
Docker 상태 점검
로그 분석
Nginx 설정 변경
인증서 상태 점검
AI 에이전트 개발 환경
ChatGPT나 MCP 지원 에이전트가 실제 Ubuntu 서버를 개발 머신처럼 사용할 수 있다.
AI의 추론
+
MCP Tool 호출
+
실제 Linux 환경
이 세 가지가 연결되기 때문에 단순 코드 생성기보다 훨씬 능동적인 개발 에이전트를 구성할 수 있다.
16. 가장 중요한 주의점: 강력한 만큼 위험하다
cokacremote의 장점과 위험은 사실 같은 곳에서 나온다.
권한 제한이 거의 없는 원격 개발 환경이라는 점이다.
다음과 같은 명령도 기술적으로 실행 가능하다.
패키지 설치·삭제
서비스 시작·중단
방화벽 설정 변경
시스템 파일 수정
파일 영구 삭제
Docker 관리
특히 remove_path는 휴지통을 사용하지 않고 바로 삭제한다.
따라서 공개 서버에 배포한다면 최소한 다음 원칙은 지키는 것이 좋다.
- Node.js 서비스 자체는 가능하면 localhost에만 bind한다.
- 외부 접근은 Nginx HTTPS를 통한다.
- 강력하고 충분히 긴 인증 토큰을 사용한다.
- OAuth 또는 신뢰할 수 있는 인증 게이트웨이를 사용한다.
- MCP endpoint를 익명으로 인터넷에 노출하지 않는다.
- 인증 토큰을 root 비밀번호에 준하는 비밀정보로 취급한다.
- 중요 시스템에서는 별도의 저권한 서비스 계정을 검토한다.
AI가 서버 전체를 다룰 수 있다는 것은 편리하지만, 잘못된 요청도 서버 전체에 영향을 줄 수 있다는 뜻이다.
정리
cokacremote를 직접 분석해보니 단순한 "원격 명령 실행 MCP"보다 범위가 넓었다.
핵심을 요약하면 다음과 같다.
| 구분 | 내용 |
|---|---|
| 목적 | ChatGPT/MCP 클라이언트에서 Linux 서버 원격 개발 |
| 언어 | Node.js + TypeScript |
| MCP 도구 | 총 20개 |
| 실행/프로세스 | 6개 |
| 파일 시스템 | 14개 |
| 스크립트 | Bash, sh, Node.js, Python, custom |
| 전송 | Stateless Streamable HTTP JSON |
| 인증 | Bearer + OAuth 2.1/DCR/PKCE |
| 배포 | systemd + Nginx 예제 제공 |
| 파일 접근 | 호스트 전체 경로 접근 가능 |
| 테스트 | 22개 테스트 모두 통과 |
개인적으로 가장 의미 있는 부분은 AI가 명령 한 번만 실행하는 것이 아니라 장시간 프로세스를 관리하고, 파일을 구조적으로 편집하고, 테스트와 배포까지 하나의 작업 흐름으로 이어갈 수 있다는 점이다.
예전에는 AI에게 코드를 받은 뒤 사람이 SSH로 서버에 접속해서 복사하고, 실행하고, 오류를 다시 전달해야 했다. cokacremote 같은 MCP 서버를 연결하면 그 사이의 반복 작업 상당 부분을 AI 에이전트가 직접 수행할 수 있다.
다만 이것은 샌드박스 개발 도구가 아니다. AI에게 서버의 손과 발을 달아주는 도구에 가깝다. 그래서 편리함만큼 인증, 권한 관리, HTTPS, 백업 전략이 중요하다.
향후에는 cokacremote를 이용해 실제로 ChatGPT가 Ubuntu 서버에서 프로젝트 생성 → 코드 작성 → Docker 배포 → Nginx HTTPS 연결 → Playwright UI 검증까지 진행하는 전체 개발 흐름도 별도로 정리해볼 만하다.