ftp-deploy-mcp

AI 코딩 에이전트를 위한 배포 버튼. Claude Code · Claude Desktop · Cursor · Windsurf · Trae · Antigravity → 나만의 FTP / FTPS / SFTP 서버.

Version française → README.fr.md

에이전트가 배포를 실행합니다 — 당신은 그저 요청만 하면 됩니다.

왜 필요한가

• 모든 웹 프로젝트는 결국 같은 결말에 이릅니다: "이제 서버에 올려야지."

• AI 에이전트는 훌륭한 코드를 작성하지만, 클래식 호스팅에 안전하게 배포할 방법이 없습니다 — OVH, Ionos, Hostinger, o2switch 등 공유 호스팅의 대부분은 여전히 FTP/SFTP를 사용하며 git push를 지원하지 않습니다.

• ftp-deploy-mcp는 모든 MCP 클라이언트에게 코드가 작성된 바로 그 대화 속에서 나만의 인프라로 배포할 수 있는 경로를 제공합니다.

• 일반적인 SSH-exec MCP 서버와 달리, 이 서버는 파일 배포에 특화되어 있습니다: 경로 잠금(jail), 읽기 전용 모드, 드라이런(dry-run), 그리고 모델의 컨텍스트에 절대 들어가지 않는 자격 증명.

Related MCP server: mcp-remote-ssh

기능

빠른 시작

1. git clone https://github.com/alebgl77/ftp-deploy-mcp.git && cd ftp-deploy-mcp

2. install.cmd 실행 (Windows, 더블클릭) 또는 ./install.sh 실행 (macOS / Linux).

3. IDE를 재시작하고 에이전트에게 말하세요: "prod에 ./dist를 배포해 줘."

작동 방식

flowchart LR
subgraph agents [AI agents]
  A[Claude Code]; B[Cursor]; C[Windsurf]; D[Trae]; E[Antigravity]
end
agents -- MCP stdio --> S[ftp-deploy-mcp<br/>10 tools · path jail · read-only guard]
S -- FTP / FTPS --> F[(your web hosts)]
S -- SFTP --> G[(your servers)]
K[ftp-servers.json<br/>credentials stay local] -.-> S

1. 무엇인가

MCP(Model Context Protocol) 서버로, stdio를 통해 실행되며 코딩 에이전트에게 10개의 도구를 제공합니다. 자격 증명은 로컬 설정 파일에 저장되며 LLM 컨텍스트를 통과하지 않습니다. 모든 원격 작업은 서버별로 선택한 root 아래로 제한됩니다.

Node.js >= 18 필요. 컴파일할 네이티브 의존성 없음.

2. 설치

⚡ 원커맨드 설치 (권장)

git clone https://github.com/alebgl77/ftp-deploy-mcp.git
cd ftp-deploy-mcp

그런 다음 마법사를 실행하세요:

• Windows: install.cmd 더블클릭.

• macOS / Linux: ./install.sh 실행 (chmod +x install.sh 먼저 필요한 경우).

• 또는 수동으로: npm install && npm run setup.

setup 마법사는 모든 것을 처리합니다:

• 서버 설정을 작성하거나 가져옵니다 (기존 사이트의 FileZilla 가져오기 포함);

• 각 서버에 대한 연결을 테스트합니다;

• 감지된 MCP 클라이언트(Claude Code, Claude Desktop, Cursor, Windsurf, Antigravity)의 설정 파일을 자동으로 작성합니다 — 기존 파일을 수정하기 전에 .backup-<날짜> 백업을 만든 후;

• Trae용 붙여넣기 준비 완료 블록을 출력하고 클립보드에 복사합니다 (Trae는 UI에서 설정하므로).

그런 다음 IDE를 재시작하고 에이전트에게 말하세요, 예: "내 FTP 서버 목록을 보여 줘".

진단

언제든지, 읽기 전용 진단(아무것도 쓰지 않음):

npm run doctor          # or: node src/index.js doctor

Node 버전, 사용 중인 설정 파일, 서버 목록(비밀번호 제외), 그리고 각 클라이언트별로 ftp 항목이 이 설치에 연결되어 있는지 여부를 출력합니다.

setup 옵션 (node src/index.js setup [options]):

(b) 전역 설치

npm install -g .

ftp-deploy-mcp 명령이 이제 PATH에 있습니다. node .../src/index.js 대신 이 명령을 사용하세요.

(c) npm에 게시 (npx 사용 시)

이 패키지를 npm에 자신의 이름으로 게시하면, 클라이언트는 사전 설치 없이 실행할 수 있습니다:

{ "command": "npx", "args": ["-y", "your-package-name"] }

3. 서버 설정

ftp-servers.json 파일을 만드세요. 서버는 다음 순서로 파일을 찾습니다 (먼저 찾은 것이 우선):

1. --config <path> (명령줄 플래그)

2. FTP_MCP_CONFIG 환경 변수 (JSON 경로)

3. ./ftp-servers.json (프로세스 작업 디렉터리)

4. ~/.ftp-mcp/servers.json

전체 스키마

{
  "defaultServer": "prod",          // optional: used when "server" is not given
  "servers": {
    "prod": {
      "protocol": "sftp",           // REQUIRED: "ftp" | "ftps" | "sftp"
      "host": "ssh.example.com",    // REQUIRED
      "port": 22,                    // optional (defaults: ftp/ftps 21, implicit ftps 990, sftp 22)
      "user": "deploy",             // REQUIRED
      "password": "${ENV:PROD_PW}", // optional: password (or an env placeholder)
      "privateKeyPath": "~/.ssh/id_ed25519", // optional (sftp); "~" is expanded
      "passphrase": "…",            // optional: private-key passphrase
      "root": "/var/www/site",      // optional (default "/"): ALL ops are jailed under it
      "readOnly": false,             // optional: blocks upload/deploy/mkdir/rename/delete
      "insecureTLS": false,           // optional (ftps): skip certificate checks — requires "allowInsecure"
      "implicitTLS": false,          // optional (ftps): implicit TLS (port 990, legacy servers)
      "allowInsecure": false         // optional: explicit opt-in REQUIRED for plain "ftp" or "insecureTLS"
    }
  }
}

위 블록의 // 주석은 설명을 위한 것입니다. 실제 파일은 엄격한 JSON이어야 합니다 (주석 불가). ftp-servers.example.json 참조.

환경 변수 치환

모든 문자열 값에는 ${ENV:VARIABLE_NAME}을 포함할 수 있습니다. 시작 시 환경 변수의 값으로 대체됩니다. 변수가 설정되어 있지 않으면 도구는 누락된 변수를 명시하는 명확한 오류를 반환합니다.

"password": "${ENV:OVH_FTP_PASSWORD}"

보안 팁

• SFTP를 선호하세요. 일반 ftp 및 insecureTLS: true인 ftps는 기본적으로 거부됩니다: 해당 전송 방식에서는 네트워크 공격자가 자격 증명이나 파일을 가로채거나 변조할 수 있습니다. 어쨌든 사용하려면 해당 서버에 명시적으로 "allowInsecure": true를 설정해야 합니다 — 그러면 모든 시작 로그와 도구 결과에 보이는 보안 경고가 표시됩니다.

• ftp-servers.json을 .gitignore에 추가하세요 (이 저장소에는 이미 되어 있음).

• 파일 권한을 제한하세요 (Unix에서 chmod 600 ftp-servers.json).

• 평문 비밀번호 대신 환경 변수(${ENV:…}) 또는 SSH 키를 선호하세요.

• 에이전트가 절대 쓰면 안 되는 서버에는 readOnly: true를 사용하세요.

• root를 가능한 한 좁게 설정하세요: 잠금(jail)이 모든 ../ 탈출을 방지합니다.

4. FileZilla에서 가져오기

이미 FileZilla에 사이트가 있나요? 변환하세요:

# Auto-detect the default sitemanager.xml location…
node src/index.js import-filezilla

# …or an explicit file, written to an ftp-servers.json
node src/index.js import-filezilla --file /path/sitemanager.xml --out ./ftp-servers.json

--out 없이 실행하면 JSON이 표준 출력으로 출력됩니다. Base64로 인코딩된 비밀번호는 디코딩됩니다. 저장된 비밀번호가 없는 사이트는 ${ENV:<NAME>_PASSWORD} 자리 표시자를 받습니다 (변수는 직접 설정). 출력 예시:

{
  "defaultServer": "my-site",
  "servers": {
    "my-site": {
      "protocol": "ftp",
      "host": "ftp.example.com",
      "user": "deploy",
      "password": "…",
      "root": "/www/html"
    }
  }
}

주의: 생성된 파일에는 디코딩된 평문 비밀번호가 포함되어 있습니다 — 버전 관리(.gitignore)에서 제외하고 권한을 제한하세요 (chmod 600).

일반 FTP 사이트: 가져온 "protocol": "ftp" 서버(위 예시와 같은)는 sftp/ftps로 전환하거나 명시적으로 "allowInsecure": true를 설정할 때까지 연결 시 거부됩니다 — 가져오기 시 각각에 대해 경고가 출력됩니다. 보안 참조.

5. 수동 클라이언트 설정 (setup을 사용하지 않는 경우)

npm run setup이 이 파일들을 자동으로 작성합니다 (백업 포함). 이 섹션은 모든 것을 직접 연결하고 싶을 때만 유용합니다.

/absolute/path/to/ftp-deploy-mcp/src/index.js를 실제 경로로 바꾸세요 (Windows에서도 슬래시 / 사용 가능). 패키지를 npm에 게시했다면 "command": "node", "args": ["…/src/index.js"]를 "command": "npx", "args": ["-y", "your-package-name"]로 교체하세요.

아래 파일 위치는 작성 시점의 기본 위치입니다. 이 제품들의 UI는 계속 진화하므로 필요 시 해당 문서를 확인하세요.

Claude Code

프로젝트 루트 .mcp.json:

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

또는 한 줄 명령으로:

claude mcp add ftp -- node /absolute/path/to/ftp-deploy-mcp/src/index.js

Claude Desktop

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Cursor

~/.cursor/mcp.json (전역) 또는 .cursor/mcp.json (프로젝트):

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Trae

Trae에는 안정적인 설정 파일이 없습니다 — 모든 것이 UI에서 처리됩니다. AI 채팅 패널 → 설정/기어 → MCP → 추가 → 수동 구성을 선택한 다음 붙여넣으세요 (이것이 setup이 출력하고 클립보드에 복사하는 블록입니다):

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Antigravity

버전에 따라 파일은 다음 중 하나입니다:

• ~/.gemini/antigravity/mcp_config.json

• 변형: ~/.gemini/config/mcp_config.json

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

에이전트의 MCP 패널(MCP 서버 관리) → 서버 추가를 사용할 수도 있으며, 동일한 구조를 사용합니다.

6. 10가지 도구

모든 원격 경로(path, remote_path, …)는 서버 root 기준이며 POSIX 스타일을 사용합니다. server 매개변수는 항상 선택 사항입니다 (아래 해석 규칙 참조).

서버 결정 방식: 명시적 server 매개변수 → defaultServer → 서버가 하나뿐이면 해당 서버 → 그 외에는 사용 가능한 이름 목록을 오류로 반환.

ftp_deploy 기본 제외 패턴: **/node_modules/**, **/.git/**, .env, .env.*, *.log, .DS_Store, Thumbs.db, ftp-servers.json, **/.ftp-mcp/** (사용자 exclude 글로브는 추가됨; include는 일치하는 파일로 제한). 슬래시 없는 패턴은 모든 깊이에서 일치 (gitignore 방식): 중첩된 apps/api/.env도 제외됨.

7. 예시 프롬프트

• "./dist를 prod 서버에 배포해."

• "ovh의 /www에 무엇이 있는지 나열해."

• "prod에서 .htaccess를 가져와서 보여줘."

• "./build를 /www에 배포하는 시뮬레이션(dry run)을 실행해 어떤 파일이 전송될지 확인하고 싶어."

• "prod에서 index.old.html을 index.html로 이름을 변경해."

8. 보안

• 기본적으로 보안 전송 사용: 일반 FTP 및 인증서 검증이 비활성화된(insecureTLS: true) FTPS는 서버 항목이 명시적으로 "allowInsecure": true를 설정하지 않으면 거부됨. 허용된 경우, 시작 시, ftp_list_servers에서, doctor에서, 그리고 해당 서버의 모든 도구 결과에 보안 경고가 추가됨.

• 루트 감옥(Root jail): 모든 작업은 정규화된 후 서버 root 내에 머무르는지 검증됨. root가 /인 경우에도 이탈 시도(../…)는 거부됨.

• 읽기 전용: readOnly: true는 모든 쓰기 작업(업로드, 배포, 디렉터리 생성, 이름 변경, 삭제)을 차단; 읽기는 계속 허용됨.

• LLM에 자격 증명 노출 금지: 비밀번호, 암호문구 및 키는 도구 출력에 절대 반환되지 않음.

• 원격 측정 없음: 자신의 서버 외부로 나가는 연결 없음.

• 호출별 연결: 각 도구는 연결을 열고, 작업을 수행하고, 연결을 닫음 — 지속적인 세션 없음.

9. 문제 해결

• 시간 초과 / 연결 불가 (FTP): 일반적으로 방화벽에 의해 **수동 모드(passive mode)**가 차단됨. 서버의 수동 포트에 연결할 수 있는지 확인.

• SFTP 키 인증: privateKeyPath 설정 (~는 확장됨), 키가 암호화된 경우 passphrase 설정. 키 권한 확인.

• "안전하지 않은 연결 거부됨": 서버가 일반 FTP를 사용하거나 인증서 검증이 비활성화된 FTPS를 사용함. sftp(또는 유효한 인증서가 있는 ftps)로 전환하거나 — 차단 위험을 완전히 수용하는 경우에만 해당 서버에 "allowInsecure": true를 설정.

• 자체 서명 FTPS: insecureTLS: true는 검증되지 않은 인증서를 수락함. 이는 중간자 공격 방지를 비활성화하므로 "allowInsecure": true도 필요하며 모든 호출에 보안 경고를 출력함. 유효한 인증서를 설치하는 것이 좋음.

• 암시적 FTPS (포트 990): implicitTLS: true (ftps 프로토콜) 설정은 레거시 서버용으로, AUTH TLS 명령 없이 첫 바이트부터 암호화함.

• "서버가 구성되지 않음": 4개 위치에서 파일을 찾지 못함. ftp-servers.json을 생성하거나 --config <path> / FTP_MCP_CONFIG=<path>를 전달.

• setup 후 클라이언트에 도구가 표시되지 않음: IDE를 완전히 다시 시작 (프로젝트만 닫지 말고 모든 창 닫기), 그런 다음 npm run doctor로 연결을 확인.

• 잘못된 구성으로도 서버가 시작됨: 이는 의도된 동작입니다 (MCP 클라이언트는 시작 시 죽는 서버를 싫어함). 정확한 오류는 시작 시 stderr에 출력되고 모든 도구 호출에 반환됨.

개발

npm test          # runs the full smoke test (local FTP + SFTP, no external network)
node src/index.js --version
node src/index.js --help

기여

기여를 환영합니다 — 개발 환경 설정, 프로젝트 원칙 및 PR 체크리스트는 CONTRIBUTING.md를 참조하세요.

보안

취약점을 발견하셨나요? 공개 이슈를 열지 마시고 — 비공개로 신고하는 방법은 SECURITY.md를 참조하세요.

라이선스

MIT — LICENSE 참조.