cloudflare-dns-mcp-server

MCP 호환 LLM 클라이언트(Claude Code, Claude Desktop, claude.ai 커스텀 커넥터, Cursor 등)가 Cloudflare 계정의 DNS 레코드를 읽고 편집할 수 있게 해주는 Model Context Protocol(MCP) 서버입니다. 스트리밍 가능한 HTTP 서버(원격 서버용 현재 MCP 표준인 무상태 JSON 모드)로 실행되며, 로컬 하위 프로세스 서버를 실행하는 클라이언트를 위한 stdio 모드도 지원합니다.

도구

Related MCP server: cloudflare-dns-mcp-server

설정

Node.js 20+ 필요.

1. 범위가 제한된 Cloudflare API 토큰을 생성합니다. Cloudflare 대시보드에서 My Profile → API Tokens → Create Token으로 이동하여 Edit zone DNS 템플릿을 사용하고, Zone Resources에서 모델이 관리하려는 특정 영역으로 제한하세요. Global API Key는 사용하지 마세요 — 범위가 제한된 토큰은 최악의 경우에도 해당 영역의 DNS로만 피해가 한정됩니다.

2. 설치 및 빌드:

npm install
npm run build

3. 구성 및 실행:

cp .env.example .env   # fill in tokens, then either export them or use a loader
export CLOUDFLARE_API_TOKEN="cf_..."
export MCP_AUTH_TOKEN="$(openssl rand -hex 24)"   # protects the MCP endpoint itself
npm start

MCP 엔드포인트는 이제 http://127.0.0.1:8787/mcp에 있습니다(헬스 체크는 /healthz). 환경 변수: HOST(기본값 127.0.0.1), PORT(기본값 8787), TRANSPORT(http 기본값 또는 stdio), ALLOWED_ORIGINS(추가 브라우저 오리진, 쉼표로 구분).

4. 스모크 테스트:

MCP_AUTH_TOKEN="<same token>" npm run smoke

실제 MCP 클라이언트로 연결하여 8개 도구를 나열하고 cloudflare_verify_token을 호출합니다. MCP Inspector를 URL에 연결할 수도 있습니다: npx @modelcontextprotocol/inspector.

클라이언트 연결

Claude Code:

claude mcp add --transport http cloudflare-dns http://127.0.0.1:8787/mcp \
  --header "Authorization: Bearer $MCP_AUTH_TOKEN"

Cursor / JSON 구성이 있는 기타 클라이언트 — 커스텀 헤더로 스트리밍 가능한 HTTP를 지원하는 모든 클라이언트는 동일한 방식으로 작동합니다:

{
  "mcpServers": {
    "cloudflare-dns": {
      "url": "http://127.0.0.1:8787/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

로컬 stdio 서버만 실행하는 클라이언트:

{
  "mcpServers": {
    "cloudflare-dns": {
      "command": "node",
      "args": ["/path/to/cloudflare-dns-mcp-server/dist/index.js"],
      "env": { "CLOUDFLARE_API_TOKEN": "cf_...", "TRANSPORT": "stdio" }
    }
  }
}

claude.ai / Claude 모바일 커스텀 커넥터는 공개 HTTPS URL이 필요합니다 — localhost에는 연결할 수 없습니다. 가장 빠른 방법은 서버를 실행 중인 머신에서 Cloudflare Tunnel을 사용하는 것입니다:

cloudflared tunnel --url http://127.0.0.1:8787

중요한 주의사항: claude.ai 커스텀 커넥터 UI는 OAuth를 통해서만 인증하거나 인증 없이 작동합니다 — 정적 bearer 헤더를 위한 필드가 없습니다. 따라서 원격 사용에는 두 가지 옵션이 있습니다: 터널을 Cloudflare Access(서비스 인증) 뒤에 두고 해당 계층에서 인증을 종료하거나, MCP_AUTH_TOKEN을 설정하지 않고 실행하여 터널 URL의 비밀 유지에 의존하는 것입니다 — DNS를 편집할 수 있는 것에 비해 현저히 약한 보호입니다. Cloudflare Tunnel을 사용하면 서버가 여전히 127.0.0.1에 바인딩되므로 별도의 옵트인이 필요 없습니다. 그러나 터널링 대신 포트를 직접 노출하는 경우, 인증되지 않은 비-localhost 바인딩에는 ALLOW_UNAUTHENTICATED=true가 필요합니다. 선택 전에 현재 claude.ai 커넥터 인증 옵션을 확인하세요. 이는 시간이 지남에 따라 변경됩니다.

보안 참고 사항

서버는 기본적으로 127.0.0.1에 바인딩되며 CLOUDFLARE_API_TOKEN 없이는 시작을 거부합니다. MCP_AUTH_TOKEN이 설정되지 않은 상태에서 다른 주소에 바인딩하면 시작을 거부합니다 — 포트에 접근할 수 있는 사람은 누구나 DNS를 편집할 수 있기 때문입니다. 단, ALLOW_UNAUTHENTICATED=true를 설정한 경우는 예외이며, 이는 인증이 업스트림(예: Cloudflare Access)에서 종료되는 경우에만 적절합니다. 브라우저 오리진 요청은 localhost 또는 ALLOWED_ORIGINS에서 온 경우가 아니면 거부됩니다(DNS 리바인딩 보호). 토큰은 환경에서 읽히며, 로그에 기록되지 않고, 어떤 도구에서도 반환되지 않습니다.

모델 안전성 측면에서: 삭제에는 명시적인 confirm=true 인수가 필요하고, 업데이트는 변경 전/후 상태를 반환하여 모든 변경을 되돌릴 수 있으며, cloudflare_export_zone은 한 번의 호출로 BIND 백업을 제공합니다 — 대량 편집 전에 모델에게 실행하도록 요청할 가치가 있습니다. DNS 편집은 실제 인터넷에 전파됩니다. 잘못된 레코드는 사이트나 메일을 오프라인 상태로 만들 수 있으므로, 프로덕션 영역에 적용하기 전에 모델이 제안하는 내용을 검토하세요.

개발

npm run build    # compile TypeScript → dist/
npm start        # run HTTP server
npm run smoke    # end-to-end client test against the running server

소스 구조: src/index.ts(전송, 인증 미들웨어), src/cloudflare.ts(API 클라이언트, 영역 해석, 포맷팅), src/tools.ts(도구 등록).

라이선스

MIT