Zendesk MCP Server (Extended Edition)

A production-grade Model Context Protocol (MCP) server for Zendesk — run it locally with Claude Desktop over stdio, or deploy it to the cloud as a secure, multi-tenant, OAuth-protected remote MCP server that any AI application can connect to.

Note — extension of the original project

This is an extended fork of reminia/zendesk-mcp-server. The original provides a local, stdio-only Zendesk MCP server with basic ticket tools. This edition keeps full backward compatibility with it (stdio mode, original tools, prompts, and knowledge-base resource) and extends it for remote, internet-facing production use.

Issues with the original repo that this edition addresses

Feature overview

Original features (retained):

• Ticket tools: get ticket, list tickets, get comments, create ticket, update ticket, comment on ticket

• Image attachment download with security hardening (MIME allowlist, magic-byte validation, 10 MB cap)

• Prompts: analyze-ticket, draft-ticket-response

• Resource: zendesk://knowledge-base (all Help Center articles, cached 1 h)

• stdio transport for Claude Desktop / Claude Code local use

New in this edition:

• Streamable HTTP transport with /health endpoint

• Internal API keys: zmk_ prefix, SHA-256 hashed at rest, scopes, expiry, instant revocation, audit log

• OAuth 2.1 resource server: JWKS/issuer/audience JWT validation, RFC 9728 Protected Resource Metadata at /.well-known/oauth-protected-resource/mcp — works with Auth0, Descope, Cognito, Keycloak, WorkOS

• Scope model: tickets:read, tickets:write, kb:read, * — enforced per tool, fail-closed, with tools/list filtering

• Optional elicitation: in-client approve/decline before posting public (customer-visible) comments

• Dual Zendesk identity: reads via a restricted user (e.g. light agent), writes via a full agent

• Multi-tenancy with per-tenant Zendesk credentials

• Web admin console: connection settings (hot-swap + test), tenant management, key lifecycle

• New tools: search_tickets, get_user, search_users, list_groups, list_ticket_fields, search_articles, upload_attachment

• Tool annotations (readOnlyHint / destructiveHint) and structured output on all tools

• Deployment: Dockerfile, docker-compose + Caddy (auto-TLS), Terraform for EC2 and ECS Fargate

• MCP Registry manifest (server.json) and publishing guide

Tools

Prompts: analyze-ticket, draft-ticket-response. Resource: zendesk://knowledge-base (kb:read).

Quick start (local, stdio — same as the original)

git clone <this-repo>
cd zendesk-mcp-server
uv venv && uv pip install -e .
cp .env.example .env   # fill in ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, ZENDESK_API_KEY

Claude Desktop config:

{
  "mcpServers": {
    "zendesk": {
      "command": "uv",
      "args": ["--directory", "/path/to/zendesk-mcp-server", "run", "zendesk"]
    }
  }
}

stdio mode is trusted-local: no auth, full access, identical behavior to the original repo.

Remote mode (Streamable HTTP)

MCP_TRANSPORT=http zendesk        # serves http://0.0.0.0:8000/mcp  +  /health

Create scoped API keys (shown once, stored hashed):

zendesk-keys create --name "reader"  --scopes tickets:read,kb:read
zendesk-keys create --name "agent"   --scopes tickets:read,tickets:write,kb:read --expires-days 30
zendesk-keys create --name "admin"   --scopes "*"
zendesk-keys list
zendesk-keys revoke --id 2

Connect a client:

claude mcp add zendesk --transport http https://mcp.example.com/mcp \
  --header "Authorization: Bearer zmk_..."

Read-only keys never see write tools in tools/list; write calls without tickets:write are denied; unknown tools are denied by default (fail closed).

Configuration reference

All configuration is via environment variables (or .env; the admin console can override connection settings at runtime, persisted in the key-store DB).

Zendesk connection

*Either ZENDESK_EMAIL or both ZENDESK_READ_EMAIL/ZENDESK_WRITE_EMAIL. Zendesk roles live on the user, not the token — pairing the same token with a restricted user email yields restricted permissions (Layer 4 backstop).

Transport

Authentication

Admin console & safety

Security model

Multi-tenancy

By default every caller uses the server's own Zendesk connection. To let other teams/customers connect their Zendesk:

1. Admin console → Tenants → add name, subdomain, API token, read/write emails.

2. Bind credentials to the tenant: create an API key with that tenant selected (or zendesk-keys create ... --tenant-id N), or configure your IdP to issue the tenant's name/id in the MCP_OAUTH_TENANT_CLAIM JWT claim.

3. All tool calls from that identity are routed to the tenant's Zendesk. Deleting a tenant revokes its keys immediately.

Web admin console

Enable with MCP_ADMIN_PASSWORD. Reach it via tunnel — never expose it:

ssh -L 9000:localhost:9000 user@host          # or the SSM equivalent, see docs/DEPLOYMENT.md
# open http://localhost:9000

Provides: Zendesk connection editor with hot-swap (no restart) and "test connection", tenant management, API key create/revoke with scope checkboxes and expiry, and key usage visibility. Stored tokens are never re-displayed; new keys are shown exactly once.

Deployment

Docker (single container):

docker build -t zendesk-mcp-server .
docker run --rm -p 8000:8000 --env-file .env -v zmcp-keys:/data zendesk-mcp-server

Docker Compose + automatic TLS (recommended single-box): set MCP_DOMAIN in .env, then docker compose up -d — Caddy terminates TLS with Let's Encrypt and proxies to the server. Create keys with docker compose exec zendesk-mcp zendesk-keys create ....

AWS EC2 (Terraform): terraform/ provisions EC2 (SSM access, no SSH, IMDSv2), security group (80/443 only), Elastic IP, optional Route53, and bootstraps Docker + the repo. Full runbook: docs/DEPLOYMENT.md.

Windows Server without Docker: native Python + Caddy with your own TLS certificate + NSSM services, including a troubleshooting FAQ of real-world Windows issues (Node/PATH, cert chains, arg mangling): docs/WINDOWS_SETUP.md.

AWS ECS Fargate + ALB (scale-out): terraform/ecs/ provisions ECR, Fargate service, ALB with ACM/TLS 1.3, EFS-backed key store, Secrets Manager injection, and CloudWatch. Keep desired_count=1 until the key store is migrated off SQLite.

MCP Registry: fill in server.json and follow docs/REGISTRY.md to publish your deployed server to registry.modelcontextprotocol.io.

Development

uv sync --extra dev
uv run pytest tests/ -v        # 38 tests: tools, keystore, permissions, tenancy, auth modes

Project layout:

src/zendesk_mcp_server/
  server.py          # FastMCP app: tools, prompts, resources, transports
  zendesk_client.py  # Zendesk API client (dual identity, cursor pagination)
  auth.py            # API-key verifier, OIDC JWT verifier, auth-mode factory
  permissions.py     # Scope model + enforcement/filtering middleware
  keystore.py        # SQLite: keys, tenants, audit log
  runtime.py         # Client holder: hot-swap + per-tenant routing
  admin.py           # Web admin console (separate port)
  keys_cli.py        # zendesk-keys CLI
  config.py          # Env-based settings
terraform/           # EC2 deployment     terraform/ecs/  # Fargate deployment
docs/                # Architecture plan, deployment runbook, registry guide

Architecture decisions and full history: docs/REMOTE_MCP_ARCHITECTURE_PLAN.md.

License

Apache 2.0 — same as the original project. Original work by reminia; extensions as described above.