zendesk-mcp

A custom MCP (Model Context Protocol) server for Zendesk support workflows, built with Node + TypeScript and the official @modelcontextprotocol/sdk.

What it does

Exposes four tools that Claude (or any MCP client) can call:

Related MCP server: Zendesk MCP Server

Tool reference

Each tool's parameters are defined by its inputSchema in src/tools/*.ts — that file is the source of truth if this table drifts. Params are passed as a JSON object matching the schema below.

Calling a tool through Claude

Describe what you want in plain language — Claude fills in the parameters:

Run summarize_daily_work for 2026-07-20
Search similar tickets for "PDF export hangs on large files", top 10
Get customer context for jane@example.com
Get customer context for the organization Anthology

Calling a tool via raw MCP JSON-RPC

This is the tools/call request the client actually sends (see test-client.mjs for a working example):

{
  "method": "tools/call",
  "params": {
    "name": "summarize_daily_work",
    "arguments": {
      "date": "2026-07-20",
      "assignee": "sophia.banda@nutrient.io"
    }
  }
}

Omit any optional argument to fall back to its default (e.g. omit date for "today", omit assignee to scope to ZENDESK_EMAIL).

Calling a tool from a plain terminal (no Claude Code needed)

The server is just a Node process speaking MCP over stdio — any MCP client can talk to it, including a terminal script. Use run.mjs (loads your real .env, unlike test-client.mjs which uses fake credentials for smoke testing):

node run.mjs <tool_name> '<json_args>'

# examples
node run.mjs get_customer_context '{"organization":"Anthology"}'
node run.mjs get_customer_context '{"requesterEmail":"jane@example.com"}'
node run.mjs summarize_daily_work '{"date":"2026-07-20"}'
node run.mjs search_similar_tickets '{"issue":"PDF export hangs on large files","topK":10}'

Run npm run build first if you've made source changes — this calls the compiled server in build/, not the TypeScript source directly.

How it's put together

src/
  clients/
    zendesk.ts     – thin wrapper over the Zendesk REST API (search, tickets, users, orgs)
    vectorDb.ts     – adapter interface (VectorDb) + a mock implementation + a generic HTTP
                      implementation, so the real backend can be swapped in via .env only
  tools/
    searchSimilarTickets.ts
    customerInfo.ts
    assessSolutions.ts
    dailySummary.ts
  index.ts          – wires everything together and starts the server over stdio
test-client.mjs      – a tiny MCP client used to sanity-check the server without wiring it into Claude

Why the adapter pattern for the vector DB

The exact shape of the backing RAG index isn't fixed yet. Rather than hard-coding a client, vectorDb.ts defines a one-method interface:

interface VectorDb {
  search(query: string, topK?: number): Promise<VectorMatch[]>;
}

Everything else in the codebase (the tools) only depends on that interface, not on a specific backend. VECTOR_DB_PROVIDER=mock in .env gives a fake in-memory index for building and testing end-to-end. Once the real index's API is known:

• use the built-in HttpVectorDb if there's a query endpoint in front of it (adjust the request/response shape in vectorDb.ts to match the actual API), or

• add a new class (e.g. PineconeVectorDb, QdrantVectorDb) implementing the same interface, and add a case for it in vectorDbFromEnv().

No changes needed anywhere else.

Setup

npm install
cp .env.example .env   # fill in your Zendesk subdomain/email/API token
npm run build

.env fields:

• ZENDESK_SUBDOMAIN / ZENDESK_EMAIL / ZENDESK_API_TOKEN — from Zendesk Admin Center > Apps and integrations > APIs > Zendesk API. Generate a token there and enable token access.

• VECTOR_DB_PROVIDER — mock to start; switch once you have real connection info.

Running it standalone (for testing)

node test-client.mjs

This spawns the built server, lists its tools, and calls assess_solutions_by_version against the mock vector data — useful for iterating without wiring the server into an actual MCP client.

Registering it with Claude

Add it to your MCP client config (e.g. Claude Desktop's claude_desktop_config.json, or Claude Code's .mcp.json):

{
  "mcpServers": {
    "zendesk-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/zendesk-mcp/build/index.js"],
      "env": {
        "ZENDESK_SUBDOMAIN": "your-company",
        "ZENDESK_EMAIL": "you@company.com",
        "ZENDESK_API_TOKEN": "...",
        "VECTOR_DB_PROVIDER": "mock"
      }
    }
  }
}

Notes / open items

(Internal notes — may be stale, keep or prune as they're resolved.)

1. The real vector index's query interface isn't confirmed yet (REST endpoint? Python service? direct DB connection to Pinecone/Qdrant/pgvector/etc). That determines whether HttpVectorDb works as-is, needs tweaking, or a new adapter class is needed.

2. Once wired to the real index, revisit the metadata shape assess_solutions_by_version expects (fixedInVersion, product, tags) — align it with whatever fields the index actually stores per chunk.

3. Consider adding a list_products or list_versions tool if there's a canonical version list to validate customerVersion against.

4. Add tests (e.g. with node --test) for compareVersions in assessSolutions.ts — it's a naive semver comparator and worth hardening for versions like 8.4.2-rc1.