Zendesk Help Center MCP Server

A read-only MCP (Model Context Protocol) server for querying public Zendesk Help Center APIs. Lets AI agents browse, search, and fetch documentation from any public Zendesk Help Center.

Features

Browse Help Center structure (categories, sections, articles)
Fetch article content as clean markdown
Search articles by keyword
Browse community posts and comments
Locale-aware (filter by language)
HTTP response caching (7-day TTL via hishel)
Works with any public Zendesk Help Center (no auth required)

Installation

Requires Python 3.10+.

git clone <repo-url>
cd zendesk
uv sync

Or with pip:

pip install -e .

Configuration

Claude Code

Add a .mcp.json file to your project root (or any project that needs Zendesk HC access):

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

Replace /path/to/zendesk-hc-mcp with the absolute path to where you cloned this repo. Do not use ~ — tilde expansion does not work in MCP config.

Claude Desktop

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

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

Note: uv must be on PATH for the MCP host process to find it.

Available Tools

All tools take subdomain as the first parameter (e.g., "support.zendesk.com"). All tools accept force_refresh=True to bypass the cache. Most tools accept an optional locale parameter (e.g., "en-us", "ru") to filter by language.

Structure Browsing

Tool	Description
`list_categories(subdomain, locale?)`	Entry point: shows locales, categories, and section counts
`list_sections(subdomain, category_id?, locale?)`	Sections, optionally filtered by category

Content Retrieval

Tool	Description
`get_article(subdomain, article_id)`	Single article with full markdown body
`get_articles(subdomain, article_ids)`	Batch fetch multiple articles concurrently
`get_section_articles(subdomain, section_id, locale?, include_body?, max_articles?)`	TOC by default; set `include_body=True` for full text
`search_articles(subdomain, query, locale?, limit?)`	Keyword search with snippets (no bodies)

Community

Tool	Description
`list_community_topics(subdomain)`	Forum topics
`list_community_posts(subdomain, topic_id?, limit?)`	Posts with body previews and comment counts
`get_community_post(subdomain, post_id)`	Full post with comments

Usage Examples

Discover a Help Center's structure:

list_categories("support.zendesk.com")

Browse sections in a category:

list_sections("support.zendesk.com", category_id=360001006608)

Fetch all articles in a section (TOC only):

get_section_articles("support.zendesk.com", section_id=360000031847)

Fetch articles with full content:

get_section_articles("support.zendesk.com", section_id=360000031847, include_body=True, max_articles=5)

Search for articles:

search_articles("support.zendesk.com", query="API")

Cache

Responses are cached for 7 days in .cache/ (project-local) using hishel (SQLite-backed HTTP cache).

Use force_refresh=True on any tool to bypass the cache
Delete the .cache/ directory to clear all cached data
The .cache/ directory is gitignored

Override the default TTL (in seconds) with the ZENDESK_HC_CACHE_TTL environment variable in your .mcp.json:

{
  "mcpServers": {
    "zendesk-hc": {
      "command": "uv",
      "args": ["--directory", "/path/to/zendesk-hc-mcp", "run", "zendesk-hc-mcp"],
      "env": {
        "ZENDESK_HC_CACHE_TTL": "86400"
      }
    }
  }
}

Development

# Install dev dependencies
uv sync

# Run tests
uv run pytest -v

# Run the server (stdio mode)
uv run zendesk-hc-mcp

Contributing

Contributions are welcome! To get started:

Fork the repository
Create a feature branch (git checkout -b feature/my-feature)
Install dev dependencies: uv sync
Make your changes following TDD (write tests first)
Run the test suite: uv run pytest -v
Ensure coverage stays above 90%: uv run pytest --cov=zendesk_hc_mcp --cov-report=term-missing
Submit a pull request

See CLAUDE.md for architecture details and development conventions.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Zendesk, Inc. "Zendesk" is a registered trademark of Zendesk, Inc. This tool accesses the publicly available Zendesk Help Center API and is intended for lawful, read-only use.

License

MIT