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:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Install dev dependencies: uv sync
4. Make your changes following TDD (write tests first)
5. Run the test suite: uv run pytest -v
6. Ensure coverage stays above 90%: uv run pytest --cov=zendesk_hc_mcp --cov-report=term-missing
7. 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