zendesk-mcp

Servidor MCP do Zendesk: leitura/escrita de tickets, comentários, anexos, controle de tempo e configuração baseada em OAuth. Integração opcional com Git-Zen.

GitHub

Experimente este MCPPatrocinado

Documentação

zendesk-mcp

Um servidor Model Context Protocol que expõe ferramentas de leitura e escrita de tickets do Zendesk para o Claude Code e outros clientes MCP.

O que ele faz

Pesquisar, listar (com paginação) e buscar tickets, comentários e anexos do Zendesk
Criar novos tickets e atualizar campos de tickets existentes (incluindo grupo, status personalizado e tags)
Publicar respostas públicas e notas internas
Definir o status do ticket e atribuir tickets a agentes
Navegar e aplicar visualizações e macros
Consultar usuários, grupos, organizações e status personalizados
Ler e gravar entradas de controle de tempo
Formatar um ticket como um rascunho de issue em Markdown para transferência a um rastreador (GitLab, GitHub, Jira)
Dois prompts MCP (analyze-ticket, draft-ticket-response) para análise de tickets e elaboração de respostas
(Opcional) Expor artigos da Central de Ajuda do Zendesk como um recurso MCP
(Opcional) Ler issues / MRs / commits vinculados do GitLab por meio do aplicativo Git-Zen do Zendesk

Pré-requisitos

Python 3.10 ou mais recente
Um cliente OAuth do Zendesk. Um administrador do Zendesk pode criar um em: https://<your-subdomain>.zendesk.com/admin/apps-integrations/apis/zendesk-api/oauth_clients Defina a URL de redirecionamento para http://localhost:8787/callback e solicite os escopos read write.

Instalação

Instale em um virtualenv local do projeto. Usar um venv mantém o zendesk-mcp e suas dependências isolados do Python do sistema e de outros projetos, sendo o caminho recomendado para tudo abaixo.

A partir de um clone deste repositório:

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

Para desenvolvimento (também instala o pytest):

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

Ao longo deste README, os comandos usam os binários do venv via .venv/bin/.... Você pode, em vez disso, source .venv/bin/activate uma vez por shell e remover o prefixo — o resultado é o mesmo.

Configuração OAuth

Execute a configuração interativa usando o Python do venv:

.venv/bin/python -m zendesk_mcp setup

Você será solicitado a fornecer:

Seu subdomínio do Zendesk (ex.: acme para acme.zendesk.com)
O ID do cliente OAuth criado pelo seu administrador
O segredo do cliente OAuth
(Opcional) Um ID de campo de integração Git-Zen — consulte Opcional: Integração Git-Zen
(Opcional) Se deseja habilitar o recurso de base de conhecimento da Central de Ajuda — consulte Opcional: Base de conhecimento da Central de Ajuda

A configuração abre um navegador para a etapa de autorização OAuth e, em seguida, grava um token em ~/.config/zendesk-mcp/config.json (modo 0600).

Se você não tiver um navegador, a URL será exibida no terminal — abra-a em qualquer dispositivo, clique em Permitir e cole a URL de redirecionamento resultante de volta no prompt.

Expiração e renovação do token

Os tokens de acesso do Zendesk expiram. Clientes OAuth criados em ou após 30/04/2026 recebem uma vida útil padrão de 30 minutos; clientes mais antigos emitem tokens sem expiração, a menos que uma expiração seja solicitada. A configuração solicita um token de acesso de 24 horas e um token de atualização de 90 dias, para que o comportamento seja o mesmo em ambos os casos, e o servidor renova o token de acesso automaticamente — antes de expirar, e novamente se o Zendesk rejeitar um token no meio de uma solicitação.

Para tornar isso possível, o arquivo de configuração também armazena refresh_token, expires_at, client_id e client_secret junto com o token de acesso. Mantenha o arquivo no modo 0600; ele tem o mesmo nível de confiança que o próprio token de acesso. Se o seu cliente OAuth não retornar um token de atualização, a configuração informa isso e o token é usado como está.

Execute novamente .venv/bin/python -m zendesk_mcp setup quando:

o token de atualização expirar (90 dias sem uso), ou
você revogar a concessão OAuth no Zendesk.

Em ambos os casos, as ferramentas retornam Zendesk authorization failed: ... Re-run: zendesk-mcp setup em vez de falharem de forma opaca.

Registrar com o Claude Code

Registre o servidor MCP usando o Python do venv por caminho absoluto. O Claude Code inicia o servidor em um shell novo que não herda o seu venv ativado, portanto o caminho absoluto é obrigatório — apontar para um python simples aqui falhará ao importar 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

Ou apenas insira o caminho absoluto que você deseja:

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

Em seguida, adicione as ferramentas de leitura a permissions.allow em ~/.claude/settings.json para evitar prompts por chamada:

{
  "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"
    ]
  }
}

As ferramentas de escrita (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) não estão intencionalmente na lista de permissões padrão — o Claude solicitará sua confirmação a cada chamada.

Ferramentas

Tickets

Ferramenta	O que ela faz
`zendesk_search_tickets`	Pesquisar tickets por status, prioridade, tipo, responsável, solicitante, tags ou palavra-chave
`zendesk_get_tickets`	Listar tickets com paginação e ordenação (página, itens por página, ordenar por, ordem de ordenação)
`zendesk_get_ticket`	Obter os metadados de um ticket
`zendesk_create_ticket`	Criar um novo ticket (assunto, descrição, prioridade/tipo/ID do responsável/ID do solicitante/tags/campos personalizados opcionais)
`zendesk_update_ticket`	Atualizar um ou mais campos em um ticket existente (status, prioridade, assunto, tipo, ID do responsável, ID do solicitante, ID do grupo, ID do status personalizado, tags, campos personalizados, data de vencimento)
`zendesk_get_comments`	Obter o thread da conversa em um ticket
`zendesk_list_attachments`	Listar anexos em um ticket
`zendesk_download_attachment`	Baixar um anexo para um diretório de cache local
`zendesk_ticket_to_gitlab_context`	Formatar um ticket e sua conversa como um rascunho de issue em Markdown
`zendesk_post_comment`	Publicar uma resposta pública em um ticket
`zendesk_post_internal_note`	Publicar uma nota interna somente para agentes em um ticket
`zendesk_set_ticket_status`	Definir o status do ticket (`new`, `open`, `pending`, `hold`, `solved`, `closed`)
`zendesk_assign_ticket`	Atribuir um ticket a um agente por e-mail ou `me`

Ferramenta	O que ela faz
`zendesk_add_tag`	Adicionar uma tag a um ticket (idempotente)
`zendesk_remove_tag`	Remover uma tag de um ticket (idempotente)

Visualizações e Macros

Ferramenta	O que ela faz
`zendesk_list_views`	Listar todas as visualizações ativas
`zendesk_get_view`	Obter as condições de filtro e as configurações de execução de uma visualização
`zendesk_get_view_tickets`	Buscar tickets que correspondem atualmente a uma visualização
`zendesk_list_macros`	Listar macros ativas com suas ações
`zendesk_preview_macro`	Visualizar quais alterações uma macro faria
`zendesk_apply_macro`	Aplicar uma macro a um ticket (aplica alterações de campos e publica qualquer comentário)

Usuários, Grupos e Organizações

Ferramenta	O que ela faz
`zendesk_search_users`	Encontrar usuários por nome ou e-mail
`zendesk_get_groups`	Listar todos os grupos ativos
`zendesk_get_group_users`	Listar os membros de um grupo
`zendesk_get_organization`	Buscar uma organização, incluindo campos personalizados
`zendesk_list_custom_statuses`	Listar todos os status personalizados de tickets e seus IDs

Controle de tempo

Ferramenta	O que ela faz
`zendesk_get_time_tracking`	Ler entradas de controle de tempo de um ticket
`zendesk_log_time`	Registrar uma entrada de tempo em um ticket

Integração Git-Zen

Ferramenta	O que ela faz
`zendesk_get_git_zen_links`	(Somente Git-Zen) Obter issues / MRs / commits vinculados do GitLab para um ticket

Prompts

O servidor expõe dois prompts MCP que alguns clientes (ex.: Claude Desktop) apresentam como comandos de barra:

Prompt	Argumento	O que ele faz
`analyze-ticket`	`ticket_id`	Pede ao modelo para buscar o ticket e produzir um resumo, status/linha do tempo e pontos-chave de interação
`draft-ticket-response`	`ticket_id`	Pede ao modelo para buscar o ticket e redigir uma resposta voltada ao cliente (com uma etapa de confirmação antes de publicar)

Opcional: Integração Git-Zen

Se a sua instância do Zendesk usa o aplicativo Git-Zen, a ferramenta zendesk_get_git_zen_links pode ler o payload do campo personalizado dele. Encontre o ID do campo personalizado Git-Zen da sua instância em Admin → Tickets → Campos (é um ID numérico) e, em seguida, defina-o durante o .venv/bin/python -m zendesk_mcp setup ou edite o ~/.config/zendesk-mcp/config.json para adicionar:

{
  "git_zen_field_id": 12345678901234
}

Sem essa configuração, o zendesk_get_git_zen_links retorna uma mensagem de "não configurado".

Opcional: Base de conhecimento da Central de Ajuda

Se a sua instância do Zendesk tiver uma Central de Ajuda publicada, você pode expor suas seções e artigos como o recurso MCP zendesk://knowledge-base. O recurso retorna um único documento JSON cobrindo todas as seções e artigos, armazenado em cache por uma hora.

Isso é opcional. Habilite-o respondendo "s" ao prompt durante o .venv/bin/python -m zendesk_mcp setup ou adicionando o seguinte ao ~/.config/zendesk-mcp/config.json:

{
  "knowledge_base_enabled": true
}

Quando a flag estiver ausente ou for falsa, o recurso não é registrado, mantendo a lista de recursos do servidor vazia para instâncias sem uma Central de Ajuda.

Desenvolvimento

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

Os testes são executados em Python 3.10, 3.11 e 3.12 no CI (consulte .github/workflows/test.yml).

Lançamento

Aumente a versão em pyproject.toml, mcpb/pyproject.toml (tanto a versão quanto o pin de zendesk-mcp==), mcpb/manifest.json e server.json (ambos os campos), e então envie uma tag v*. Isso aciona .github/workflows/release.yml, que publica no PyPI, empacota o bundle MCPB, publica server.json no Registro MCP e cria o lançamento no GitHub.

Verifique se as versões concordam antes de criar a tag — o lançamento falha rapidamente caso contrário:

python3 .github/scripts/check_versions.py 0.1.5

Licença

Apache-2.0

zendesk-mcp

Documentação

zendesk-mcp

O que ele faz

Pré-requisitos

Instalação

Configuração OAuth

Expiração e renovação do token

Registrar com o Claude Code

Ferramentas

Tickets

Tags

Visualizações e Macros

Usuários, Grupos e Organizações

Controle de tempo

Integração Git-Zen

Prompts

Opcional: Integração Git-Zen

Opcional: Base de conhecimento da Central de Ajuda

Desenvolvimento

Lançamento

Licença