zendesk-admin-mcp

A local MCP server for Zendesk administration work. Zendesk adopted MCP on the client side — its agentic AI consumes external servers — but never shipped a server of its own that a host application could use. This fills that gap, with a deliberately narrow scope.

It does not wrap the whole API. It exposes 12 tools covering four concrete admin jobs, because a server with 200 tools floods the context window and makes the model choose worse.

You: "Which triggers haven't fired in the last 30 days?"
     "Who has the heaviest open backlog right now?"
     "Maria is leaving on Friday — what's still assigned to her?"

• Purpose

• Features

• Security model

• Requirements

• Installation

• Configuration

• Connecting it

• Verification

• Limitations

• Troubleshooting

• Implementation notes

• Contributing

• License

• Author

Purpose

Zendesk admin work involves a lot of questions that are tedious to answer through the UI: which business rules are dead weight, where the backlog is piling up, who still holds admin privileges, and what is left hanging when an agent leaves. Each of those means clicking through several admin screens and cross-referencing by hand.

This server turns those questions into tool calls an AI assistant can make directly, and returns aggregated summaries rather than raw record dumps, so the model can reason about the answer instead of drowning in it.

Related MCP server: mcp-server-zendesk

Features

Connection

Business-rule auditing

Backlog and SLAs

Security

Users and offboarding

Security model

Three layers, in order of importance:

1. The token's Zendesk role is the real boundary. The server can never do more than that user could already do in the UI. If you want a read-only server, give it a token belonging to a user with read-only permissions.

2. Writes are off by default. reassign_tickets and set_user_status fail with a clear message while ZENDESK_ALLOW_WRITES is not true.

3. Dry run by default. Even with writes enabled, both tools report what they would change without touching anything, until you call them with dry_run=false.

Each tool is also advertised to the MCP client with readOnlyHint or destructiveHint, so the host can prompt you for confirmation before the ones that modify data.

Credential handling

No credential is ever written into the source tree. The server reads everything from environment variables, and authentication travels in an HTTP header rather than a URL, so it cannot leak into a logged request line.

Depending on how you install it, your token lives in one of three places:

If you fork or clone this repo, keep .env out of version control. The shipped .gitignore already excludes .env, dist/, and *.mcpb.

A note on API tokens

Zendesk has marked API tokens as deprecated and recommends OAuth. Their own documentation warns that an API token allows impersonating any member of the account, admins included. For a local prototype they are fine; if this reaches production or more than one person, move to OAuth. The server accepts both.

Requirements

• Python 3.10 or newer

• A Zendesk account and a token (API token or OAuth)

• For recent_admin_changes: the Zendesk Enterprise plan

• For list_sla_policies: a plan that includes SLAs

Installation

git clone https://github.com/Grjhoan/Zendesk_MCP_Server.git
cd Zendesk_MCP_Server
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Configuration

Copy .env.example to .env and fill it in, or define the variables directly in your MCP client's configuration.

To generate an API token: Admin Center → Apps and integrations → APIs → Zendesk API → Settings, enable Token access and create one. Save it right then; Zendesk will not show it again.

If both are set, ZENDESK_OAUTH_TOKEN wins.

Connecting it

Claude Desktop — as an extension (recommended)

This bundles the dependencies, so the extension does not depend on your virtualenv, and stores the token in your OS keychain instead of a plain-text file.

./build_mcpb.sh

Then open Settings → Extensions → Advanced settings and either:

• Install extension… → pick the generated zendesk-admin.mcpb, or

• Install unpacked extension… → pick the dist/ folder (not the project root — only dist/ has the rewritten manifest).

Claude will prompt you for the subdomain, credentials and the write toggle.

Build the bundle on the machine you will install it on. It vendors platform-compiled wheels and pins the absolute path of the interpreter that built it, so a bundle built on Linux will not start on macOS. This is also why dist/ and *.mcpb are git-ignored — they are never portable.

Claude Desktop — manual configuration

In ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "zendesk-admin": {
      "command": "/absolute/path/to/zendesk-admin-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/zendesk-admin-mcp/server.py"],
      "env": {
        "ZENDESK_SUBDOMAIN": "acme",
        "ZENDESK_EMAIL": "you@company.com",
        "ZENDESK_API_TOKEN": "...",
        "ZENDESK_ALLOW_WRITES": "false"
      }
    }
  }
}

Use absolute paths: the client does not launch the server from this folder. Restart Claude Desktop after editing.

Claude Code

claude mcp add zendesk-admin \
  --env ZENDESK_SUBDOMAIN=acme \
  --env ZENDESK_EMAIL=you@company.com \
  --env ZENDESK_API_TOKEN=... \
  --env ZENDESK_ALLOW_WRITES=false \
  -- /absolute/path/.venv/bin/python /absolute/path/server.py

Then confirm it is connected:

claude mcp list

Any other MCP client

The server speaks MCP over stdio. Point your client at .venv/bin/python server.py with the environment variables above.

Verification

python tests/test_client.py      # HTTP layer against a mock transport
python tests/test_handshake.py   # real MCP handshake and tool listing

Both run without credentials or network access. After that, with credentials in place:

python check_connection.py       # probes every endpoint the tools rely on

This reports which endpoints answer for your account and plan, which is the fastest way to find out what will work before connecting the server to a client. Finally, ask the model to call whoami — the quickest confirmation that the connection and role are what you expect.

Limitations

• Read-heavy by design. Only two tools write. This is not a general-purpose Zendesk automation server.

• Plan-gated features. recent_admin_changes needs Enterprise; list_sla_policies needs a plan with SLAs. Both degrade to an explanatory message rather than an error.

• Results are bounded. Every tool caps how much it fetches and returns a truncated flag when it hits the cap. On very large accounts, treat the numbers as a well-sampled picture rather than a full census.

• Single account per server instance. Credentials are read once from the environment at startup.

• Local only. stdio transport, one operator, one set of credentials. There is no multi-user HTTP transport yet.

• No caching. Repeated audits spend fresh rate-limit quota each run.

• usage_30d is not universal. Zendesk reports it for triggers and macros but not automations, where it comes back null.

Troubleshooting

Implementation notes

Verified against the official Zendesk documentation:

• Authentication: basic auth with the {email}/token:{api_token} form in base64, or Bearer for OAuth.

• Pagination: cursor-based (page[size], links.next, meta.has_more). Offset pagination is capped at 100 pages and 10,000 records, so it is unused.

• Rate limits: on a 429 the Retry-After header is honoured, with up to 4 retries and a 60-second ceiling per wait.

• Search: /search/export rather than /search, because the latter caps at 1,000 total results. The export cursor expires after one hour.

• Bulk writes: update_many accepts 100 ids per call and processes asynchronously via job_status.

The Python MCP SDK is on 2.x, where FastMCP was renamed MCPServer. pyproject.toml pins mcp>=2.0,<3.

Contributing

Issues and pull requests are welcome. Please run both test suites before submitting, and never commit a .env, a built dist/, or a .mcpb bundle.

Ideas that would push this further:

• Streamable HTTP transport with OAuth 2.1, so several admins can connect from claude.ai or another host with their own credentials.

• A read cache, to avoid spending rate-limit quota on audits that run often.

• Tools for views, forms and groups, if the business-rule audit proves useful.

License

MIT — see LICENSE. You are free to use, modify and distribute this in your own environment, commercial or otherwise.

Author

Jhoan Zabala

• Web: jhoanzabala.com

• Email: jzabalacx@gmail.com

Not affiliated with or endorsed by Zendesk. "Zendesk" is a trademark of Zendesk, Inc.