Claude Code에서 Coolify MCP 연동하기: 인프라 관리 자동화

개요

Coolify는 Heroku, Vercel의 셀프호스팅 대안으로, 자체 서버에서 애플리케이션을 손쉽게 배포할 수 있는 플랫폼입니다. Claude Code의 MCP(Model Context Protocol)를 활용하면 AI 에이전트가 직접 Coolify 인프라를 관리할 수 있습니다.

이 글에서는 Claude Code에 Coolify MCP를 연동하는 전체 과정과 실제 활용 방법을 설명합니다.

사전 준비

1. Coolify 설치

Coolify가 설치된 서버가 필요합니다. 아직 설치하지 않았다면 공식 문서를 참고하세요:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

2. API 토큰 발급

Coolify 대시보드에서 API 토큰을 발급받습니다:

1. Coolify 대시보드 접속 (예: http://your-server:8000)
2. Settings → API Tokens 메뉴 이동
3. "Create New Token" 클릭
4. 토큰 이름 입력 (예: "claude-code-mcp")
5. 생성된 토큰 복사 (다시 볼 수 없으므로 안전하게 보관)

Claude Code MCP 설정

글로벌 설정 방식

모든 프로젝트에서 Coolify MCP를 사용하려면 ~/.claude.json 파일에 설정합니다:

{
  "mcpServers": {
    "coolify": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@masonator/coolify-mcp"],
      "env": {
        "COOLIFY_BASE_URL": "http://YOUR_SERVER_IP:8000",
        "COOLIFY_ACCESS_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

프로젝트별 설정 방식

특정 프로젝트에서만 사용하려면 프로젝트 루트의 .mcp.json 파일에 설정합니다:

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["-y", "@masonator/coolify-mcp"],
      "env": {
        "COOLIFY_BASE_URL": "http://YOUR_SERVER_IP:8000",
        "COOLIFY_ACCESS_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

설정 항목 설명

항목	설명
type	MCP 통신 방식 (stdio: 표준 입출력)
command	MCP 서버 실행 명령어
args	-y: 자동 설치 허용, 패키지명
COOLIFY_BASE_URL	Coolify 대시보드 URL
COOLIFY_ACCESS_TOKEN	발급받은 API 토큰

설정 확인

Claude Code를 재시작한 후 /mcp 명령어로 연결 상태를 확인합니다:

# Claude Code 터미널에서
/mcp

Coolify MCP가 정상 연결되면 도구 목록에 다음과 같은 항목들이 표시됩니다:

• mcp__coolify__list_servers
• mcp__coolify__list_applications
• mcp__coolify__deploy
• mcp__coolify__application_logs

주요 기능과 활용 예시

1. 서버 상태 확인

Claude에게 서버 상태를 물어볼 수 있습니다:

"현재 Coolify 서버 상태를 확인해줘"

Claude가 list_servers, diagnose_server 도구를 사용해 서버 리소스 사용량, 연결 상태 등을 분석합니다.

2. 애플리케이션 배포

새 버전 배포를 자연어로 요청할 수 있습니다:

"backend 애플리케이션을 재배포해줘"

Claude가 해당 애플리케이션을 찾아 deploy 명령을 실행합니다.

3. 로그 조회 및 문제 진단

배포 실패 시 로그를 확인하고 문제를 분석할 수 있습니다:

"web 애플리케이션 배포 로그를 확인하고 에러 원인을 분석해줘"

4. 환경 변수 관리

애플리케이션의 환경 변수를 조회하거나 수정할 수 있습니다:

"backend 서비스의 환경 변수 목록을 보여줘"

5. 인프라 전체 현황

전체 인프라 상태를 한눈에 파악할 수 있습니다:

"Coolify에 배포된 모든 서비스 현황을 정리해줘"

Coolify MCP 연동의 장점

1. 컨텍스트 스위칭 최소화

코드 작업 중 배포가 필요할 때 대시보드로 이동할 필요 없이 Claude Code 내에서 바로 처리할 수 있습니다. 개발 흐름이 끊기지 않습니다.

2. 자연어 인터페이스

복잡한 CLI 명령어나 API 호출을 외울 필요 없이 자연어로 요청하면 됩니다. Claude가 적절한 도구를 선택하고 실행합니다.

3. 문제 진단 자동화

배포 실패 시 로그를 수집하고 원인을 분석하는 과정이 자동화됩니다. "왜 배포가 실패했는지 분석해줘"라고 요청하면 됩니다.

4. 코드-인프라 연계 작업

코드 변경 후 배포까지 한 번에 처리할 수 있습니다:

"이 버그를 수정하고, 커밋한 다음 production에 배포해줘"

5. 다중 서비스 관리

여러 서비스를 동시에 관리할 때 유용합니다. 프로젝트 전체 서비스의 상태를 확인하거나 일괄 재시작이 가능합니다.

6. 학습 곡선 최소화

Coolify API나 CLI를 별도로 학습할 필요 없이 Claude를 통해 모든 작업을 처리할 수 있습니다.

보안 고려사항

토큰 관리

• API 토큰은 .claude.json에 저장되며, 이 파일은 Git에 커밋하지 않습니다
• 정기적으로 토큰을 갱신하는 것이 좋습니다
• 최소 권한 원칙을 적용하여 필요한 권한만 부여하세요

네트워크 설정

• Coolify 서버가 인터넷에 노출된 경우 방화벽으로 접근을 제한하세요
• 가능하면 VPN이나 내부 네트워크를 통해 접근하는 것이 안전합니다

트러블슈팅

MCP 연결 실패

/mcp에서 coolify가 보이지 않으면:

1. Claude Code 재시작
2. 설정 파일 JSON 문법 확인
3. npx가 정상 동작하는지 확인: npx -y @masonator/coolify-mcp --help

인증 오류

401 에러가 발생하면:

1. API 토큰이 유효한지 확인
2. 토큰에 필요한 권한이 있는지 확인
3. COOLIFY_BASE_URL이 정확한지 확인

타임아웃

서버 응답이 느리면:

1. 네트워크 연결 상태 확인
2. Coolify 서버 리소스 사용량 확인
3. 방화벽 설정 확인

마무리

Coolify MCP를 Claude Code에 연동하면 인프라 관리가 개발 워크플로우의 자연스러운 일부가 됩니다. 코드 작성, 테스트, 배포까지 Claude Code 하나로 처리할 수 있어 생산성이 크게 향상됩니다.

특히 1인 개발자나 소규모 팀에서 DevOps 전담 인력 없이 인프라를 관리할 때 유용합니다. AI 에이전트가 반복적인 인프라 작업을 대신 처리해주므로 개발에 더 집중할 수 있습니다.