Command-Line MCP Server

Model Context Protocol 원격 서버로, 단일 도구 run_command를 노출하여 Claude(Claude Desktop Connectors 기능을 통해)가 이 서버를 실행 중인 머신에서 셸 명령을 실행할 수 있게 합니다.

이 서버는 OAuth 2.1(Dynamic Client Registration + PKCE)을 구현합니다. Claude Desktop 커넥터는 OAuth 핸드셰이크를 필수로 요구하기 때문입니다 — 인증 서버가 없는 커넥터는 로그인 시 거부됩니다. 이 서버는 인증을 자동 승인합니다(사용자 프롬프트 없음). 개인용 터널에 노출되는 서버에는 이 정도면 충분합니다.

⚠️ 보안 경고: 이 서버에 접근할 수 있고 (자동) OAuth 흐름을 완료할 수 있는 사람은 누구나 해당 사용자 권한으로 임의의 명령을 실행할 수 있습니다. 반드시 프라이빗 터널(cloudflared / ngrok)을 통해서만 노출하고, 공용 네트워크에는 절대 노출하지 마세요.

작동 방식

• 전송: Streamable HTTP(Claude Desktop 커넥터가 요구하는 전송 방식).

• 무상태(Stateless): 모든 요청은 새 서버/전송 인스턴스를 생성합니다(세션 저장소 불필요).

• 엔드포인트: POST /mcp

• 헬스 체크: GET /health

도구

run_command

셸 명령을 실행합니다. Windows에서 기본 셸은 cmd.exe입니다(ls/pwd 대신 dir, cd 사용). 단, shell: "powershell"을 전달하면 예외입니다.

get_info

OS, 아키텍처, 기본 셸(Windows에서는 cmd.exe), 현재 작업 디렉터리를 반환합니다 — 클라이언트가 어떤 셸을 사용할지 알 수 있도록 한 번 호출하세요.

read_file

텍스트 파일을 읽습니다(선택적 offset/limit 줄 범위). path는 절대 경로 또는 cwd 기준 상대 경로입니다.

list_files

디렉터리를 나열합니다. recursive: true는 트리를 탐색합니다(깊이 4로 제한).

edit_file

정확한 문자열 치환 — 코드를 편집할 때 선호되는 방식입니다(셸 이스케이프 불필요). path, old_text, new_text, 선택적 replace_all. old_text는 replace_all이 설정되지 않은 경우 고유해야 합니다. 짧은 diff를 반환합니다.

apply_patch

git apply를 통해 통합 diff를 적용합니다(--3way 폴백 포함). cwd = 저장소 루트, patch = diff 텍스트.

write_file

파일에 전체 내용을 씁니다(overwrite 또는 append).

batch_read

여러 파일을 한 번의 호출로 읽습니다. files: { path, offset?, limit? } 배열.

batch_edit

한 번의 호출로 하나 이상의 파일에 여러 정확한 텍스트 편집을 적용합니다. 트랜잭션 방식: 모든 old_text가 어떤 파일에도 쓰기 전에 검증되므로, 누락되거나 모호한 매치가 있으면 전체 배치가 중단됩니다(아무것도 변경되지 않음). 각 편집: { path, old_text, new_text, replace_all? }.

네이티브 git 패스스루

git_status(-sb), git_diff(staged + paths 옵션), git_log(max_count, revision), git_show(revision). 각각 선택적 cwd를 받습니다.

모든 파일 경로는 서버가 실행 중인 호스트에서 해석됩니다 — 이 경로는 Claude의 샌드박스가 아닌 이 머신을 가리킵니다.

로컬 실행

npm install
npm start
# server listens on http://localhost:3000/mcp

선택적 환경 변수: PORT, CMD_TIMEOUT_MS, CMD_MAX_BUFFER.

npm start는 start.js를 실행하며, 서버를 시작하기 전에 포트 3000을 해제합니다(점유 중인 프로세스를 종료). 따라서 EADDRINUSE 오류가 발생하지 않습니다.

Claude Desktop에 노출하기

옵션 A — Cloudflare Worker(안정적인 URL, trycloudflare 불필요, 도메인 불필요)

소규모 로컬 에이전트가 Cloudflare Worker에 WebSocket을 유지하며, 이 Worker가 안정적인 공개 *.workers.dev MCP 엔드포인트가 됩니다. Worker는 에이전트(PROXY_SECRET으로 인증)가 연결된 동안에만 사용자의 머신으로 중계합니다.

1. wrangler login(무료 Cloudflare 계정).

2. 배포: wrangler deploy → URL을 확인하세요(예: https://command-line-mcp.<subdomain>.workers.dev).

3. 시크릿 설정(gitignore된 .dev.vars에 이미 있는 값과 동일): wrangler secret put PROXY_SECRET(.dev.vars의 PROXY_SECRET을 붙여넣기).

4. 에이전트를 배포된 Worker에 연결: .dev.vars의 WORKER_URL을 해당 URL로 설정.

5. 사용자 머신에서 둘 다 실행:

   npm start          # the MCP server on :3000
   npm run agent      # connects to the Worker with the secret

6. Claude Desktop에서: Customize → Connectors → Add custom connector, https://command-line-mcp.<subdomain>.workers.dev/mcp를 붙여넣기.

배포 없이 로컬 테스트: wrangler dev --port 8787(Worker가 :8787에서 실행), 그 다음 npm run agent — 에이전트가 .dev.vars에서 WORKER_URL을 읽습니다.

옵션 B — cloudflared / ngrok 터널(임시 URL)

Claude Desktop 커넥터는 HTTPS URL이 필요하므로, 서버를 로컬에서 실행하고 터널링하세요:

cloudflared tunnel --url http://localhost:3000 --protocol http2
# or: ngrok http 3000

생성된 https://… URL을 복사하고 /mcp를 추가하세요(예: https://abc-123.trycloudflare.com/mcp).

Claude Desktop에 추가

1. Customize → Connectors → Add custom connector를 엽니다.

2. URL(/mcp 포함)을 붙여넣습니다(예: 옵션 A의 Worker URL).

3. 이름을 Command-Line으로 지정합니다.

4. 저장합니다. Claude가 OAuth 메타데이터를 발견하고, 클라이언트를 등록하고, 브라우저에서 (자동 승인) authorize 엔드포인트를 연 다음 리디렉션되어 준비 완료 상태가 됩니다. "OAuth Client ID"를 수동으로 입력할 필요가 없습니다 — DCR이 처리합니다.

Claude 없이 테스트

MCP Inspector를 사용하세요:

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP, URL: http://localhost:3000/mcp

강화(비개인용 사용 시)

OAuth는 이미 구현되어 있습니다(oauthProvider.js 참조). 개인용 터널을 넘어서는 용도라면 다음을 수행해야 합니다:

1. 자동 승인 authorize()를 실제 동의 화면으로 교체하거나, 최소한 허용 목록 기반의 리디렉션 URI / 클라이언트 집합을 사용하세요.

2. 클라이언트/토큰을 영속화하세요(현재는 인메모리 — 재시작 시 초기화됨).

3. 안정적인 HTTPS 도메인 뒤에서 호스팅하세요(예: VPS, Cloudflare Workers, Fly.io).

4. 허용된 명령의 허용 목록을 고려하여 피해 범위를 제한하세요.

라이선스

MIT