# Zendesk MCP Server

A Zendesk MCP (Model Context Protocol) server for Kojo. Gives Claude access to support tickets and Help Center articles for trend analysis, knowledge base management, and customer insight research.

## Example usage

- "Fetch all tickets from the past week and provide an analysis of any trends you find"
- "Pull last month's solved tickets and identify the top 5 feature gaps driving support volume"
- "Search our help center for articles about approvals — are there any gaps we should fill?"
- "Draft a new help center article explaining how to set up invoice matching"

## Tools

| Tool             | Description                                                                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `fetch_tickets`  | Search tickets by date range and status. Returns full conversation transcripts. Supports natural language dates ("past month", "past 7 days"). |
| `read_articles`  | Search, list, or get Help Center articles. Includes section discovery for browsing the knowledge base structure.                               |
| `create_article` | Create new Help Center articles (drafts by default).                                                                                           |
| `update_article` | Update article title, body, or draft status.                                                                                                   |

## Setup

### 1. Get a Zendesk API token

1. Log into Zendesk as an admin
2. Go to **Admin Center > Apps and integrations > Zendesk API**
3. Enable **Token Access** if not already enabled
4. Click **Add API token**, give it a name, and copy the token

### 2. Install and build

```bash
git clone <repo-url>
cd zendesk-mcp
npm install
npm run build
```

### 3. Configure Claude Code

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "zendesk": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/zendesk-mcp/build/index.js"],
      "env": {
        "ZENDESK_SUBDOMAIN": "your-subdomain",
        "ZENDESK_EMAIL": "your-email@example.com",
        "ZENDESK_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

Replace the `env` values with your own. The subdomain is the part before `.zendesk.com` in your Zendesk URL.

### Optional environment variables

| Variable                              | Description                                                                           |
| ------------------------------------- | ------------------------------------------------------------------------------------- |
| `ZENDESK_DEFAULT_PERMISSION_GROUP_ID` | Default permission group for new articles. If unset, Zendesk assigns its own default. |

## Requirements

- Node.js 18+
- A Zendesk account with API token access
- Claude Code with MCP support