zendesk-mcp
zendesk-mcp
Zendesk 티켓 읽기 및 쓰기 도구를 Claude Code 및 기타 MCP 클라이언트에 노출하는 Model Context Protocol 서버입니다.
기능
Zendesk 티켓, 댓글, 첨부 파일 검색, 목록(페이지네이션), 조회
새 티켓 생성 및 기존 티켓 필드 업데이트(그룹, 사용자 지정 상태, 태그 포함)
공개 답변 및 내부 메모 게시
티켓 상태 설정 및 에이전트에게 티켓 할당
보기 및 매크로 탐색 및 적용
사용자, 그룹, 조직, 사용자 지정 상태 조회
시간 추적 항목 읽기 및 쓰기
티켓을 트래커(GitLab, GitHub, Jira)로 전달하기 위한 Markdown 이슈 초안으로 포맷
티켓 분석 및 응답 초안 작성을 위한 두 개의 MCP 프롬프트(
analyze-ticket,draft-ticket-response)(선택 사항) Zendesk Help Center 문서를 MCP 리소스로 노출
(선택 사항) Git-Zen Zendesk 앱을 통해 연결된 GitLab 이슈 / MR / 커밋 읽기
Related MCP server: Zendesk MCP Server
사전 요구 사항
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다음 항목을 입력하라는 메시지가 표시됩니다:
Zendesk 하위 도메인(예:
acme.zendesk.com의 경우acme)관리자가 생성한 OAuth 클라이언트 ID
OAuth 클라이언트 시크릿
(선택 사항) Git-Zen 통합 필드 ID — 선택 사항: Git-Zen 통합 참조
(선택 사항) Help Center 지식 베이스 리소스 활성화 여부 — 선택 사항: Help Center 지식 베이스 참조
설정은 OAuth 인증 단계를 위해 브라우저를 열고, 그 후 토큰을 ~/.config/zendesk-mcp/config.json(모드 0600)에 기록합니다.
브라우저가 없는 경우 URL이 터미널에 출력됩니다 — 어떤 기기에서든 열고 Allow를 클릭한 다음, 결과 리디렉션 URL을 프롬프트에 다시 붙여넣으세요.
토큰 만료 및 갱신
Zendesk 액세스 토큰은 만료됩니다. 2026-04-30 이후에 생성된 OAuth 클라이언트는 기본 수명이 30분입니다. 이전 클라이언트는 만료가 요청되지 않는 한 만료되지 않는 토큰을 발급합니다. 설정은 24시간 액세스 토큰과 90일 갱신 토큰을 요청하므로 어느 쪽이든 동작이 동일하며, 서버는 액세스 토큰을 자동으로 갱신합니다 — 만료 전에, 그리고 Zendesk가 요청 중에 토큰을 거부하는 경우 다시 갱신합니다.
이를 가능하게 하기 위해 구성 파일에는 액세스 토큰과 함께 refresh_token, expires_at, client_id, client_secret도 저장됩니다. 파일을 모드 0600으로 유지하세요. 이는 액세스 토큰 자체와 동일한 신뢰 수준입니다. OAuth 클라이언트가 갱신 토큰을 반환하지 않으면 설정에서 이를 알리고 토큰을 그대로 사용합니다.
다음 경우에 .venv/bin/python -m zendesk_mcp setup을 다시 실행하세요:
갱신 토큰이 만료된 경우(사용하지 않으면 90일), 또는
Zendesk에서 OAuth 권한을 취소한 경우.
두 경우 모두 도구는 불투명하게 실패하는 대신 Zendesk authorization failed: ... Re-run: zendesk-mcp setup을 반환합니다.
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_tickets",
"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",
"mcp__zendesk__zendesk_list_views",
"mcp__zendesk__zendesk_get_view",
"mcp__zendesk__zendesk_get_view_tickets",
"mcp__zendesk__zendesk_list_macros",
"mcp__zendesk__zendesk_preview_macro",
"mcp__zendesk__zendesk_search_users",
"mcp__zendesk__zendesk_get_groups",
"mcp__zendesk__zendesk_get_group_users",
"mcp__zendesk__zendesk_get_organization",
"mcp__zendesk__zendesk_list_custom_statuses"
]
}
}쓰기 도구(zendesk_post_comment, zendesk_post_internal_note, zendesk_set_ticket_status, zendesk_assign_ticket, zendesk_create_ticket, zendesk_update_ticket, zendesk_log_time, zendesk_add_tag, zendesk_remove_tag, zendesk_apply_macro)는 의도적으로 기본 허용 목록에 포함되지 않습니다 — Claude가 호출할 때마다 프롬프트를 표시합니다.
도구
티켓
도구 | 설명 |
| 상태, 우선순위, 유형, 담당자, 요청자, 태그 또는 키워드로 티켓 검색 |
| 페이지네이션 및 정렬(페이지, per_page, sort_by, sort_order)로 티켓 목록 |
| 하나의 티켓 메타데이터 가져오기 |
| 새 티켓 생성(제목, 설명, 선택적 우선순위/유형/assignee_id/requester_id/태그/custom_fields) |
| 기존 티켓의 하나 이상의 필드 업데이트(상태, 우선순위, 제목, 유형, assignee_id, requester_id, group_id, custom_status_id, 태그, custom_fields, due_at) |
| 티켓의 대화 스레드 가져오기 |
| 티켓의 첨부 파일 목록 |
| 첨부 파일을 로컬 캐시 디렉토리에 다운로드 |
| 티켓과 대화를 Markdown 이슈 초안으로 포맷 |
| 티켓에 공개 답변 게시 |
| 티켓에 에이전트 전용 내부 메모 게시 |
| 티켓 상태 설정( |
| 이메일 또는 |
태그
도구 | 설명 |
| 티켓에 태그 추가(멱등) |
| 티켓에서 태그 제거(멱등) |
보기 및 매크로
도구 | 설명 |
| 모든 활성 보기 목록 |
| 보기의 필터 조건 및 실행 설정 가져오기 |
| 현재 보기와 일치하는 티켓 가져오기 |
| 활성 매크로 및 해당 작업 목록 |
| 매크로가 적용할 변경 사항 미리 보기 |
| 티켓에 매크로 적용(필드 변경 적용 및 댓글 게시) |
사용자, 그룹 및 조직
도구 | 설명 |
| 이름 또는 이메일로 사용자 찾기 |
| 모든 활성 그룹 목록 |
| 그룹의 구성원 목록 |
| 사용자 지정 필드를 포함한 조직 가져오기 |
| 모든 사용자 지정 티켓 상태 및 ID 목록 |
시간 추적
도구 | 설명 |
| 티켓의 시간 추적 항목 읽기 |
| 티켓에 시간 항목 기록 |
Git-Zen 통합
도구 | 설명 |
| (Git-Zen 전용) 티켓에 연결된 GitLab 이슈 / MR / 커밋 가져오기 |
프롬프트
서버는 일부 클라이언트(예: Claude Desktop)가 슬래시 명령으로 표시하는 두 개의 MCP 프롬프트를 노출합니다:
프롬프트 | 인수 | 설명 |
|
| 모델이 티켓을 가져와 요약, 상태/타임라인, 주요 상호 작용 지점을 생성하도록 요청 |
|
| 모델이 티켓을 가져와 고객 대면 응답 초안을 작성하도록 요청(게시 전 확인 단계 포함) |
선택 사항: 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는 "not configured" 메시지를 반환합니다.
선택 사항: Help Center 지식 베이스
Zendesk 인스턴스에 게시된 Help Center가 있는 경우 해당 섹션과 문서를 zendesk://knowledge-base MCP 리소스로 노출할 수 있습니다. 리소스는 모든 섹션과 문서를 포함하는 단일 JSON 문서를 반환하며, 1시간 동안 캐시됩니다.
이것은 선택 사항입니다. .venv/bin/python -m zendesk_mcp setup 중 프롬프트에 "y"로 답하거나 ~/.config/zendesk-mcp/config.json에 다음을 추가하여 활성화하세요:
{
"knowledge_base_enabled": true
}플래그가 없거나 false인 경우 리소스가 등록되지 않으므로 Help Center가 없는 인스턴스의 서버 리소스 목록이 비어 있게 유지됩니다.
개발
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 참조).
릴리스
pyproject.toml, mcpb/pyproject.toml(버전과 zendesk-mcp== 핀 모두), mcpb/manifest.json, server.json(두 필드 모두)에서 버전을 올린 다음 v* 태그를 푸시하세요. 그러면 .github/workflows/release.yml이 트리거되어 PyPI에 게시하고, MCPB 번들을 패킹하고, server.json을 MCP 레지스트리에 게시하고, GitHub 릴리스를 생성합니다.
태그를 지정하기 전에 버전이 일치하는지 확인하세요. 그렇지 않으면 릴리스가 즉시 실패합니다:
python3 .github/scripts/check_versions.py 0.1.5라이선스
Available Tools
29 toolszendesk_add_tagA
Add a tag to a Zendesk ticket. Idempotent: adding an existing tag returns the current tag list without modifying the ticket. Returns JSON with ticket_id and current tags.
Inputs: tag (required), ticket_id (required). Returns: result
zendesk_apply_macroA
Apply a macro to a Zendesk ticket. Fetches the macro preview, applies field changes, and posts any comment included in the macro. Returns JSON with id, status, tags, applied_changes, comment_added.
Inputs: macro_id (required), ticket_id (required). Returns: result
zendesk_assign_ticketA
Assign a Zendesk ticket to an agent by their email address. Pass 'me' as assignee_email to assign the ticket to yourself (the authenticated user).
Inputs: ticket_id (required), assignee_email (required). Returns: result
zendesk_create_ticketA
Create a new Zendesk ticket. subject and description are required. priority: low/normal/high/urgent. type: problem/incident/question/task. requester_id/assignee_id are user IDs (integers). custom_fields is a list of {id, value} dicts. Returns JSON of the created ticket.
Inputs: subject (required), description (required), tags, type, +4 more. Returns: result
zendesk_download_attachmentA
Download a Zendesk attachment. Obtain attachment_url and filename from zendesk_list_attachments. ticket_id is required for cache organization. Optional dest_dir overrides the default cache location; the file is written there and (for archives) extracted alongside it. Archives return a file list and unpack_dir — read individual files with your normal file tools. PDFs return up to ~500KB of extracted text. Images are base64-encoded.
Inputs: filename (required), ticket_id (required), attachment_url (required), dest_dir. Returns: result
zendesk_get_commentsA
Get all comments (public replies and internal notes) for a Zendesk ticket. Includes attachment metadata but does not download files.
Inputs: ticket_id (required). Returns: result
zendesk_get_git_zen_linksA
Get linked GitLab issues, merge requests, and commits for a Zendesk ticket via the Git-Zen integration. Returns structured lists with state, labels, weight, and direct GitLab links.
Inputs: ticket_id (required). Returns: result
zendesk_get_groupsA
List all active Zendesk groups (excluding deleted). Returns JSON array of {id, name}.
Inputs: no named parameters. Returns: result
zendesk_get_group_usersB
List the members of a Zendesk group. Returns JSON array of {id, name, email}.
Inputs: group_id (required). Returns: result
zendesk_get_organizationB
Fetch a Zendesk organization including its custom fields and tags. Returns JSON with id, name, organization_fields, tags, created_at, updated_at.
Inputs: organization_id (required). Returns: result
zendesk_get_ticketA
Get a Zendesk ticket by ID. Returns ticket fields including status, priority, requester, assignee, tags, and description.
Inputs: ticket_id (required). Returns: result
zendesk_get_ticketsA
List Zendesk tickets with pagination. page: 1-based page number. per_page: max 100. sort_by: created_at, updated_at, priority, or status. sort_order: asc or desc. Returns tickets plus pagination metadata.
Inputs: page, sort_by, per_page, sort_order. Returns: result
zendesk_get_time_trackingA
Get time tracking data for a Zendesk ticket. Returns total time spent and time spent on the last update, in both seconds and human-readable format (e.g. '2h 15m').
Inputs: ticket_id (required). Returns: result
zendesk_get_viewA
Get a Zendesk view's definition including filter conditions and execution settings. Returns JSON with id, title, active, conditions, execution.
Inputs: view_id (required). Returns: result
zendesk_get_view_ticketsB
Get the tickets currently matching a Zendesk view. Returns JSON array of tickets with essential fields.
Inputs: view_id (required). Returns: result
zendesk_list_attachmentsA
List all attachments across all comments for a Zendesk ticket. Returns filename, content type, size, and download URL for each. Use zendesk_download_attachment to fetch file contents.
Inputs: ticket_id (required). Returns: result
zendesk_list_custom_statusesA
List all custom ticket statuses defined in Zendesk. Returns JSON array of {id, agent_label, end_user_label, status_category, active, default}. Use the id when setting custom_status_id on a ticket.
Inputs: no named parameters. Returns: result
zendesk_list_macrosA
List all active Zendesk macros with their actions. Returns JSON array of {id, title, description, actions: [{field, value}]}.
Inputs: no named parameters. Returns: result
zendesk_list_viewsA
List all active Zendesk views. Returns JSON array of {id, title}.
Inputs: no named parameters. Returns: result
zendesk_log_timeA
Log time spent on a Zendesk ticket. Adds seconds to the running total and records it as the last-update time. Returns logged amount and new total in seconds and human-readable format.
Inputs: seconds (required), ticket_id (required). Returns: result
zendesk_post_commentA
Post a public reply on a Zendesk ticket. The reply is visible to the requester. Use for customer-facing responses.
Inputs: body (required), ticket_id (required). Returns: result
zendesk_post_internal_noteA
Post an internal note on a Zendesk ticket. Internal notes are only visible to agents and are not sent to the requester.
Inputs: body (required), ticket_id (required). Returns: result
zendesk_preview_macroA
Preview the effect a macro would have (without applying it). Returns the result payload from Zendesk's apply preview endpoint.
Inputs: macro_id (required). Returns: result
zendesk_remove_tagA
Remove a tag from a Zendesk ticket. Idempotent: removing a tag that isn't present returns the current tag list without modifying the ticket. Returns JSON with ticket_id and current tags.
Inputs: tag (required), ticket_id (required). Returns: result
zendesk_search_ticketsA
Search Zendesk tickets by keyword and/or status. keywords: free-text search (e.g. 'login failure LDAP'). status: new, open, pending, hold, solved, closed — leave empty for all statuses. Returns id, subject, status, requester, assignee, and dates.
Inputs: limit, status, keywords. Returns: result
zendesk_search_usersA
Search Zendesk users by name or email. Returns JSON array of {id, name, email, role}.
Inputs: query (required). Returns: result
zendesk_set_ticket_statusB
Set the status of a Zendesk ticket. Valid statuses: new, open, pending, hold, solved, closed.
Inputs: status (required), ticket_id (required). Returns: result
zendesk_ticket_to_gitlab_contextA
Format a Zendesk ticket and its comments as an issue draft. Returns Markdown with ticket metadata, full conversation, and an empty Steps to Reproduce section. Use this output as the description when creating an issue in your tracker.
Inputs: ticket_id (required). Returns: result
zendesk_update_ticketA
Update one or more fields on a Zendesk ticket. Pass only the fields you want to change. status: new/open/pending/hold/solved/closed. priority: low/normal/high/urgent. type: problem/incident/question/task. assignee_id, requester_id, group_id, custom_status_id are integer IDs. due_at is ISO8601. Returns JSON of the refreshed ticket.
Inputs: ticket_id (required), tags, type, due_at, +8 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 29 tools
Each tool has a clearly distinct purpose, even where operations appear similar (e.g., get_ticket, get_tickets, search_tickets). Descriptions clarify when to use each, and there is no meaningful overlap that would cause an agent to select the wrong tool.
All tools share the 'zendesk_' prefix and mostly follow a verb_noun pattern. There is some mixing between 'get_' and 'list_' for read operations, but overall the conventions are predictable and easy to follow.
With 29 tools, this exceeds the 25-tool threshold for a 'too many' rating. While the scope is broad, the high count makes the surface feel heavy and increases selection complexity, even though each tool is well-scoped individually.
The server covers the full ticket lifecycle including comments, attachments, time tracking, views, and macros. Minor gaps exist such as lack of ticket deletion and user management, but core support workflows are well represented.
Maintenance
Related MCP Connectors
Read tickets, users, orgs, macros and satisfaction ratings; create, update and comment on tickets.
Search and read Zammad tickets, customers and organizations; add notes, replies and ticket updates.
Read tickets, contacts, companies, agents and groups; create, update and reply to tickets.
Work with Enchant help desk tickets: list, read, reply, add notes and labels, manage customers.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables interaction with Zendesk to manage tickets, retrieve ticket fields, comments, and priority based on SLA, as well as get unsolved tickets by agent name.1-
- FlicenseNot gradedqualityAmaintenanceEnables users to fetch, create, and update Zendesk tickets and comments, analyze tickets and draft responses, and query Help Center articles as a knowledge base.-
- FlicenseNot gradedqualityAmaintenanceEnables integration with Zendesk to retrieve and manage tickets and comments, analyze tickets, draft responses, and access Help Center articles as a knowledge base.-
- FlicenseNot gradedqualityAmaintenanceEnables retrieving and managing Zendesk tickets and comments, accessing Help Center articles as a knowledge base, and using specialized prompts for ticket analysis and response drafting.-