@mockzilla/mcp

mockzilla용 MCP 서버입니다. Claude Desktop 및 Cursor와 같은 에이전트가 사용자를 대신하여 mockzilla를 구동할 수 있게 하며, 사용자가 계정 없이도 mockzilla를 체험해 볼 수 있도록 돕습니다.

이 브릿지는 두 가지 도구 평면을 제공합니다:

• 로컬 평면 (계정 불필요): mockzilla CLI 설치 여부 확인, 사용자용 설치(사전 빌드된 바이너리, go install 또는 go run), OpenAPI 사양 확인, 로컬에서 휴대용 모의 서버 실행 등을 수행합니다. 사용자의 컴퓨터 외부로 데이터가 나가지 않습니다.

• 호스팅 평면 (계정 필요): MOCKZILLA_TOKEN이 설정된 경우 mockzilla.org의 MCP 엔드포인트로 프록시됩니다. 시뮬레이션 목록 조회, 카탈로그에서 번들 배포 등을 수행합니다.

토큰이 없으면 로컬 평면만 사용할 수 있으며, 에이전트는 사용자가 가입하기 전에 mockzilla를 탐색하도록 도울 수 있습니다.

설치

Claude Code

설정 편집 없이 한 줄로 설치:

claude mcp add -s user mockzilla -- npx -y @mockzilla/mcp@latest

-s user는 사용자 계정에 설치합니다(모든 프로젝트에서 사용 가능). 현재 프로젝트로 범위를 제한하려면 -s user를 제거하세요.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json을 편집하세요:

{
  "mcpServers": {
    "mockzilla": {
      "command": "npx",
      "args": ["-y", "@mockzilla/mcp@latest"]
    }
  }
}

Cursor

가장 쉬운 방법: Cursor 설정 → MCP 서버 → 새 MCP 서버 추가 후 다음을 입력하세요:

• 이름: mockzilla

• 명령어: npx

• 인수: -y @mockzilla/mcp@latest

또는 ~/.cursor/mcp.json을 직접 편집하세요:

{
  "mcpServers": {
    "mockzilla": {
      "command": "npx",
      "args": ["-y", "@mockzilla/mcp@latest"]
    }
  }
}

Gemini CLI

설정 편집 없이 한 줄로 설치:

gemini mcp add -s user mockzilla npx -y @mockzilla/mcp@latest

-s user는 ~/.gemini/settings.json에 기록합니다(모든 프로젝트에서 사용 가능). 현재 디렉토리의 .gemini/settings.json으로 범위를 제한하려면 -s user를 제거(또는 -s project 사용)하세요.

또는 설정 파일을 직접 편집하세요:

{
  "mcpServers": {
    "mockzilla": {
      "command": "npx",
      "args": ["-y", "@mockzilla/mcp@latest"]
    }
  }
}

설정 편집 후 클라이언트를 재시작하세요.

왜 @latest인가요? 이를 사용하지 않으면 npx가 처음 확인된 버전을 캐시하여 새로 게시된 버전을 가져오지 않습니다. @latest로 고정하면 npx가 실행될 때마다 레지스트리를 다시 확인하므로, Claude Desktop / Cursor를 재시작하는 것만으로도 업그레이드가 가능합니다. 단점: 약 200ms의 추가 시작 시간이 소요됩니다.

요청 가능한 작업

토큰이 없는 경우 (로컬 평면):

• "mockzilla CLI가 설치되어 있나요?"

• "mockzilla를 설치해 줘." (에이전트가 다운로드 / go-install / go-run 중 선택을 요청합니다)

• "petstore 사양을 로컬에서 실행해서 curl로 테스트할 수 있게 해 줘."

• "https://example.com/openapi.yaml에는 어떤 엔드포인트가 있나요?"

• "시작한 모의 서버를 중지해 줘."

토큰이 있는 경우 (호스팅 평면 추가):

• "내가 배포한 시뮬레이션 목록을 보여줘."

• "카탈로그 제품을 보여줘."

• "stripe-test라는 이름의 Stripe 샌드박스를 배포하고 라이브 URL을 기다려 줘."

• "이 OpenAPI URL을 사용하여 mockzilla에 모의 서버를 생성해 줘."

도구

로컬

호스팅

MOCKZILLA_TOKEN이 설정된 경우 사용 가능합니다. mockzilla.org로 전달됩니다. 실시간 도구 목록은 호스팅 서버 문서를 참조하세요. 작성 시점 기준으로 get_context, list_sims, list_catalog_products, deploy_mock_from_{catalog,spec,url}, wait_for_deploy가 포함됩니다.

설정

캐시

브릿지는 모든 것을 ~/.cache/mockzilla-mcp/ 아래에 보관합니다:

~/.cache/mockzilla-mcp/
├── bin/mockzilla        # downloaded or go-installed binary
├── config.json          # {method, version, invocation?}
└── mocks/               # mock_endpoint persists static endpoints here
    └── static/
        └── <service>/<path>/<method>/index.<ext>

rm -rf ~/.cache/mockzilla-mcp는 브릿지를 완전히 초기화합니다(바이너리 + 모든 모의 엔드포인트). 모의 서버만 삭제하려면 rm -rf ~/.cache/mockzilla-mcp/mocks를 사용하세요. 시스템 PATH는 건드리지 않으므로 초기화해도 별도의 brew 설치에는 영향을 주지 않습니다.

업데이트

브릿지는 자주 업데이트됩니다. 최신 상태를 유지하는 권장 방법:

1. MCP 클라이언트 설정에서 @mockzilla/mcp@latest를 고정하여(위의 설치 스니펫 참조) npx가 실행될 때마다 레지스트리를 다시 확인하도록 합니다.

2. Claude Desktop / Cursor를 주기적으로 재시작하세요. 이때 새 버전이 가져와집니다.

3. 문제가 발생하면 에이전트에게 *"bridge_status를 실행해서 mockzilla-mcp가 최신 버전인지 알려줘."*라고 물어보세요. 구버전이라면 npx clear-npx-cache @mockzilla/mcp를 실행하고 클라이언트를 재시작하세요.

mockzilla CLI 버전은 브릿지에 의해 고정됩니다(lib/install.js의 MOCKZILLA_VERSION). 브릿지를 업데이트하면 고정 버전도 업데이트되며, 다음 install_cli 호출 시 CLI 자체가 최신 상태로 업데이트됩니다.

개발

프로젝트 규칙 및 새 도구 추가에 대한 안내는 CLAUDE.md를 참조하세요.

라이선스

MIT.