# Zendesk Skill

> Claude Skill (with cli tool) and MCP server for Zendesk

- **Type:** MCP server
- **Install:** `agentstack add mcp-andmarios-zendesk-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [andmarios](https://agentstack.voostack.com/s/andmarios)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [andmarios](https://github.com/andmarios)
- **Source:** https://github.com/andmarios/zendesk-skill

## Install

```sh
agentstack add mcp-andmarios-zendesk-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Zendesk CLI, MCP Server & Claude Code Skill

A Claude Code skill for Zendesk Support integration. The primary interface is a **skill file** (`SKILL.md`) that gives Claude full command knowledge — backed by a CLI (`zd-cli`) that Claude runs to interact with Zendesk. An MCP server is also included for other AI assistants.

> This project was built almost entirely by Claude Code through iterative conversation — designing, implementing, testing against a live Zendesk instance, and fixing issues together over multiple sessions. It's a tool I use often and am sharing in case others find it useful.

## Features

- **Claude Code skill** — `SKILL.md` gives Claude full command documentation, workflows, and the save-first/query-later pattern
- **CLI (`zd-cli`)** — 28 commands covering tickets, users, organizations, views, metrics, and more
- **MCP server** — alternative interface for other AI assistants
- **Slack integration** — send formatted support reports to Slack channels
- **Support metrics analysis** — response times, resolution rates, CSAT, after-hours and on-call tracking
- **Local response storage** — API responses saved to temp directory, queryable with jq without re-fetching
- **Markdown formatting** — write operations convert Markdown to HTML for proper rendering in Agent Workspace
- **Encrypted credentials** — API tokens and OAuth tokens encrypted at rest

## Quick Start

```bash
# Run directly (no install needed)
uvx zd-cli --help

# Set up credentials (see Authentication below)
uvx zd-cli auth login

# Verify it works
uvx zd-cli me
```

## Authentication

Three methods are supported. API token is the simplest; OAuth adds auto-refresh. A relay server mode exists for shared team deployments but is not covered here.

### Method 1: API Token

1. In Zendesk: **Admin Center → Apps and integrations → APIs → Zendesk API → Add API token**
2. Copy the token (shown only once)

```bash
# Interactive setup (prompts for email, token, subdomain)
zd-cli auth login

# Or non-interactive
zd-cli auth login --email you@company.com --token YOUR_TOKEN --subdomain yourcompany

# Or via environment variables
export ZENDESK_EMAIL="you@company.com"
export ZENDESK_TOKEN="your-api-token"
export ZENDESK_SUBDOMAIN="yourcompany"
```

### Method 2: OAuth 2.0 (with auto-refresh)

1. In Zendesk: **Admin Center → Apps and integrations → APIs → OAuth Clients → Add OAuth client**
2. Add redirect URIs for ports 8080–8089:
   ```
   http://127.0.0.1:8080/callback
   http://127.0.0.1:8081/callback
   ...
   http://127.0.0.1:8089/callback
   ```
3. Note the **Client ID** and **Client Secret**

```bash
# Opens a browser for authorization
zd-cli auth login-oauth --subdomain yourcompany --client-id YOUR_ID --client-secret YOUR_SECRET

# Headless/SSH: browser redirects to localhost (shows connection refused — that's expected),
# paste the full redirect URL back into the prompt
zd-cli auth login-oauth --subdomain yourcompany --client-id YOUR_ID --client-secret YOUR_SECRET --manual
```

```bash
# Check auth status
zd-cli auth status

# Remove credentials
zd-cli auth logout          # API token
zd-cli auth logout-oauth    # OAuth token
```

## Installation

### Via uvx (no install, recommended)

```bash
uvx zd-cli --help
```

`uvx` runs the tool in an isolated environment on demand — nothing is permanently installed.

### Via uv tool install

```bash
uv tool install zendesk-skill
zd-cli --help
```

### Development / Claude Code skill

```bash
git clone https://github.com/andmarios/zendesk-skill zendesk-skill
cd zendesk-skill
uv sync
uv run zd-cli --help
```

Point Claude Code at `SKILL.md` to give Claude full command documentation and workflows.

**Prerequisites:** Python 3.12+, [uv](https://github.com/astral-sh/uv), and `jq` (for the `query` command).

## Commands

### Tickets

| Command | Description |
|---------|-------------|
| `search "status:open priority:urgent"` | Search tickets |
| `ticket 12345` | Get ticket by ID |
| `ticket-details 12345` | Ticket + all comments |
| `linked-incidents 12345` | Incidents linked to a problem ticket |
| `attachment --ticket 12345 ` | Download an attachment |

### Write Operations

All write commands convert Markdown to HTML by default (use `--plain-text` to skip).

| Command | Description |
|---------|-------------|
| `update-ticket 12345 --status pending --tags "waiting-customer"` | Update ticket |
| `create-ticket "Subject" "**Bold** description"` | Create ticket |
| `add-note 12345 "Internal **note**"` | Add internal note |
| `add-comment 12345 "Public reply"` | Add public comment |

### Metrics & Analytics

| Command | Description |
|---------|-------------|
| `ticket-metrics 12345` | Reply/resolution times for a ticket |
| `list-metrics` | Metrics across tickets |
| `satisfaction-ratings --score bad` | CSAT ratings |

### Views

| Command | Description |
|---------|-------------|
| `views` | List available views |
| `view-count 123` | Ticket count in a view |
| `view-tickets 123` | Tickets from a view |

### Users & Organizations

| Command | Description |
|---------|-------------|
| `user 12345` | Get user by ID |
| `search-users "john@example.com"` | Search users |
| `org 67890` | Get organization by ID |
| `search-orgs "Acme"` | Search organizations |

### Configuration & Info

| Command | Description |
|---------|-------------|
| `me` | Current user (tests auth) |
| `groups` | List support groups |
| `tags` | Popular tags |
| `sla-policies` | SLA policies |

### Query

```bash
# Query a saved response file with jq
zd-cli query  -q comments_slim       # named query
zd-cli query  --jq '.data.ticket'    # custom jq
zd-cli query  --list                 # show available named queries
```

All commands save their full API response to `/tmp/zd-cli-$UID/` and print the path. Use `zd-cli query` to extract data from saved files without re-fetching.

## Search Query Syntax

```bash
# Status & priority
zd-cli search "status:open priority:urgent"
zd-cli search "status:pending assignee:me"

# Time filters
zd-cli search "created>2024-01-01 status:open"
zd-cli search "updated
  ```

Security is **enabled by default**. Configure in `~/.config/zd-cli/config.json`:

```json
{
  "security_enabled": true,
  "allowlisted_tickets": ["12345", "67890"]
}
```

- `security_enabled` — set to `false` to disable all screening and wrapping (default: `true`)
- `allowlisted_tickets` — ticket IDs to skip wrapping (for trusted/internal tickets)

```bash
# View current security status and session markers
zd-cli security-info

# Include full MCP security instructions
zd-cli security-info --instructions
```

Requires [`prompt-security-utils`](https://pypi.org/project/prompt-security-utils/) (included as a dependency).

## MCP Server

The MCP server exposes the same functionality for AI assistants that support the Model Context Protocol.

```bash
uv run zendesk-mcp
```

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "zendesk": {
      "command": "uvx",
      "args": ["--from", "zendesk-skill", "zendesk-mcp"]
    }
  }
}
```

## Development

```bash
uv run pytest -v
uv run zd-cli --help
```

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [andmarios](https://github.com/andmarios)
- **Source:** [andmarios/zendesk-skill](https://github.com/andmarios/zendesk-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-andmarios-zendesk-skill
- Seller: https://agentstack.voostack.com/s/andmarios
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.