Zendesk MCP Server with Google OAuth

This is a Model Context Protocol (MCP) server that provides comprehensive Zendesk API integration with Google OAuth authentication, deployed on Cloudflare Workers.

The server allows MCP clients (like Claude Desktop) to interact securely with Zendesk APIs through authenticated remote connections. It reads across tickets, users, organizations, the Help Center and more, and writes only macros.

Features

Zendesk API Coverage

The server reads widely and writes only macros. Reading covers:

• Tickets: List, fetch and search support tickets
• Users: List, fetch and search users
• Organizations: List, fetch and search organizations
• Groups: List and fetch agent groups
• Macros: List and fetch ticket macros
• Views: List and fetch ticket views
• Triggers: List and fetch triggers
• Automations: List and fetch automations
• Search: Search across all Zendesk data
• Help Center: Browse and search the knowledge base — articles, sections and categories
• Support: General configuration information
• Talk: Access call center statistics
• Chat: Read chat conversations

Writing is limited to creating and updating macros. Available Tools explains why, and what happens if you ask for anything else.

Technical Features

• Google OAuth Authentication: Secure user authentication flow
• Remote MCP Protocol: Streamable HTTP, stateless — each request stands alone, with no session to establish or keep alive
• Cloudflare Workers: Serverless deployment with global edge distribution
• Type Safety: Full TypeScript implementation with Zod validation
• Error Handling: Comprehensive error handling with user-friendly messages
• Modular Architecture: Easy to extend with additional tools

Getting Started

Prerequisites

• Zendesk instance with API access
• Google Cloud Platform account for OAuth
• Cloudflare account for deployment
• pnpm, which this project uses as its package manager. The exact version is pinned in package.json, and recent versions of pnpm will switch to it for you.

1. Zendesk Setup

1. In your Zendesk Admin Center, go to Apps and integrations > APIs > Zendesk API
2. Enable token access and generate an API token
3. Note your Zendesk subdomain (e.g., company from company.zendesk.com)

2. Google OAuth Setup

For Production

Create a Google Cloud OAuth App:

• Homepage URL: https://zendesk-mcp.<your-subdomain>.workers.dev
• Authorization callback URL: https://zendesk-mcp.<your-subdomain>.workers.dev/callback
• Note your Client ID and generate a Client secret

If you put the worker behind a custom domain, register that hostname here too. The worker builds its callback from whichever host the request arrived on, so connecting through https://zendesk.example.com/mcp sends Google a redirect URI of https://zendesk.example.com/callback. Registering only the workers.dev hostname is easy to misdiagnose, because every endpoint on the worker keeps answering normally and the flow fails at the Google consent screen with redirect_uri_mismatch.

For Local Development

Create a separate OAuth App for development:

• Homepage URL: http://localhost:8788
• Authorization callback URL: http://localhost:8788/callback

3. Environment Setup

Set production secrets via Wrangler:

pnpm exec wrangler secret put GOOGLE_CLIENT_ID
pnpm exec wrangler secret put GOOGLE_CLIENT_SECRET
pnpm exec wrangler secret put COOKIE_ENCRYPTION_KEY # Random string, e.g. openssl rand -hex 32
pnpm exec wrangler secret put ZENDESK_SUBDOMAIN
pnpm exec wrangler secret put ZENDESK_EMAIL
pnpm exec wrangler secret put ZENDESK_API_TOKEN
pnpm exec wrangler secret put HOSTED_DOMAIN # Optional: restrict to specific Google domain

For local development, c