zendesk-mcp

Model Context Protocol 서버로, Claude Code 및 기타 MCP 클라이언트에 Zendesk 티켓 읽기 및 쓰기 도구를 제공합니다.

주요 기능

• Zendesk 티켓, 댓글 및 첨부 파일 검색 및 가져오기

• 공개 답글 및 내부 메모 게시

• 티켓 상태 설정 및 상담원에게 티켓 할당

• 시간 추적 항목 읽기 및 쓰기

• 티켓을 추적 도구(GitLab, GitHub, Jira)로 전달하기 위한 Markdown 이슈 초안으로 서식 지정

• (선택 사항) Git-Zen Zendesk 앱을 통해 연결된 GitLab 이슈/MR/커밋 읽기

사전 요구 사항

• Python 3.10 이상

• Zendesk OAuth 클라이언트. Zendesk 관리자가 다음 경로에서 생성할 수 있습니다: https://<your-subdomain>.zendesk.com/admin/apps-integrations/apis/zendesk-api/oauth_clients 리디렉션 URL을 http://localhost:8787/callback으로 설정하고 read write 범위를 요청하세요.

설치

프로젝트 로컬 가상 환경(virtualenv)에 설치하세요. venv를 사용하면 zendesk-mcp와 그 종속성을 시스템 Python 및 다른 프로젝트와 격리할 수 있으며, 아래 모든 작업에 권장되는 방식입니다.

이 저장소를 복제한 후:

python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e .

개발용(pytest도 설치됨):

.venv/bin/pip install -e ".[dev]"

이 README 전체에서 명령어는 .venv/bin/...을 통해 venv의 바이너리를 사용합니다. 대신 셸당 한 번씩 source .venv/bin/activate를 실행하고 접두사를 생략할 수도 있습니다. 결과는 동일합니다.

OAuth 설정

venv의 Python을 사용하여 대화형 설정을 실행하세요:

.venv/bin/python -m zendesk_mcp setup

다음 항목을 입력하라는 메시지가 표시됩니다:

1. Zendesk 하위 도메인 (예: acme.zendesk.com의 경우 acme)

2. 관리자가 생성한 OAuth 클라이언트 ID

3. OAuth 클라이언트 비밀번호

4. (선택 사항) Git-Zen 통합 필드 ID — 선택 사항: Git-Zen 통합 참조

설정 과정에서 OAuth 인증 단계를 위해 브라우저가 열리고, 이후 ~/.config/zendesk-mcp/config.json (모드 0600)에 토큰이 기록됩니다.

브라우저를 사용할 수 없는 경우, URL이 터미널에 출력됩니다. 해당 URL을 다른 기기에서 열고 **허용(Allow)**을 클릭한 다음, 결과로 나오는 리디렉션 URL을 프롬프트에 다시 붙여넣으세요.

Claude Code에 등록

절대 경로를 사용하여 venv의 Python으로 MCP 서버를 등록하세요. Claude Code는 활성화된 venv를 상속하지 않는 새로운 셸에서 서버를 실행하므로 절대 경로가 필요합니다. 여기서 단순히 python을 지정하면 zendesk_mcp를 가져오는 데 실패합니다.

ZENDESK_MCP_DIR="$(pwd)"   # run this from the repo root, after install
claude mcp add --scope user zendesk -- "$ZENDESK_MCP_DIR/.venv/bin/python" -m zendesk_mcp

또는 원하는 절대 경로를 인라인으로 입력하세요:

claude mcp add --scope user zendesk -- /absolute/path/to/zendesk-mcp/.venv/bin/python -m zendesk_mcp

그런 다음 호출당 프롬프트를 피하기 위해 ~/.claude/settings.json의 permissions.allow에 읽기 도구를 추가하세요:

{
  "permissions": {
    "allow": [
      "mcp__zendesk__zendesk_get_ticket",
      "mcp__zendesk__zendesk_get_comments",
      "mcp__zendesk__zendesk_list_attachments",
      "mcp__zendesk__zendesk_download_attachment",
      "mcp__zendesk__zendesk_search_tickets",
      "mcp__zendesk__zendesk_ticket_to_gitlab_context"
    ]
  }
}

쓰기 도구(zendesk_post_comment, zendesk_post_internal_note, zendesk_set_ticket_status, zendesk_assign_ticket, zendesk_log_time)는 의도적으로 기본 허용 목록에 포함되어 있지 않으며, Claude가 호출할 때마다 승인을 요청합니다.

도구

선택 사항: Git-Zen 통합

Zendesk 인스턴스에서 Git-Zen 앱을 사용하는 경우, zendesk_get_git_zen_links 도구로 사용자 지정 필드 페이로드를 읽을 수 있습니다. 관리자 → 티켓 → 필드에서 인스턴스의 Git-Zen 사용자 지정 필드 ID(숫자 ID)를 찾은 다음, .venv/bin/python -m zendesk_mcp setup 실행 중에 설정하거나 ~/.config/zendesk-mcp/config.json을 편집하여 다음을 추가하세요:

{
  "git_zen_field_id": 12345678901234
}

이 설정이 없으면 zendesk_get_git_zen_links는 "구성되지 않음" 메시지를 반환합니다.

개발

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

테스트는 CI에서 Python 3.10, 3.11, 3.12 버전으로 실행됩니다(.github/workflows/test.yml 참조).

라이선스

Apache-2.0