Zendesk Live MCP

Read-only MCP server for complete, reconciled reporting from live Zendesk data.

It is designed for Cursor and other MCP clients. It does not use an archived SQLite database and does not modify Zendesk records.

Goal

Expose read-only Zendesk reporting tools to Cursor so users can ask questions like:

• Give me a dashboard for last 6 months tickets based on Version.
• Give me a report for customer XYZ grouped by Primary Area for Improvement for last 3 months.
• Give me a report for assignee grouped by customers for last 3 months.

Requirements

• Windows, macOS, or Linux
• Python 3.10 or newer
• Zendesk account with permission to read the required tickets and metadata
• Zendesk API token
• Cursor or another stdio-compatible MCP client

Install From Source

Clone the repository and enter its directory:

git clone https://github.com/Subrat2018/ZendeskLiveMCP.git
cd ZendeskLiveMCP

Create and activate a virtual environment:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

On macOS or Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

Copy .env.example to .env and enter the Zendesk credentials:

ZENDESK_SUBDOMAIN=your-subdomain
ZENDESK_EMAIL=you@example.com
ZENDESK_API_TOKEN=your-token

# Optional:
# ZENDESK_BASE_URL=https://your-subdomain.zendesk.com

Required values:

• ZENDESK_SUBDOMAIN: the part before .zendesk.com
• ZENDESK_EMAIL: email belonging to the Zendesk API-token owner
• ZENDESK_API_TOKEN: Zendesk API token, not the account password

Use a dedicated read-only reporting/service account where possible.

Verify

List the available live Zendesk report fields:

python -m zendesk_mcp list-fields

Example report:

python -m zendesk_mcp report --field "Version" --months 6

Customer-filtered report:

python -m zendesk_mcp report --field "Primary Area for Improvement" --months 3 --filter Customer=XYZ

Cursor MCP Config

Use the absolute path to the virtual-environment Python executable. On Windows:

{
  "mcpServers": {
    "zendesk-live": {
      "type": "stdio",
      "command": "C:/path/to/zendesk-live-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "zendesk_mcp"],
      "cwd": "C:/path/to/zendesk-live-mcp"
    }
  }
}

On macOS or Linux:

{
  "mcpServers": {
    "zendesk-live": {
      "type": "stdio",
      "command": "/path/to/zendesk-live-mcp/.venv/bin/python",
      "args": ["-m", "zendesk_mcp"],
      "cwd": "/path/to/zendesk-live-mcp"
    }
  }
}

Fully restart Cursor after changing its MCP configuration.

Test

Run the offline test suite:

python -m unittest discover -s tests -v

The tests cover complete-dataset caching, exact calendar-month handling, and rejection of reports whose ticket counts do not reconcile.

Architecture

See ARCHITECTURE.md for the component design, complete-report algorithm, correctness contract, cache behavior, security model, and failure handling.

MCP Tools

• build_ticket_dashboard: preferred tool for dashboards with several sections; fetches tickets once.
• list_report_fields: returns a compact list of available fields by default.
• dashboard_by_field: groups recent tickets by one field.
• run_ticket_report: supports filters plus one or more group-by fields.
• search_live_tickets: searches live tickets and returns compact ticket rows.
• get_live_ticket_detail: fetches one live ticket with optional comments.

Notes

• This tool is read-only.
• It uses live Zendesk APIs, not the local SQLite archive.
• Metadata lookups are cached under ZendeskMCP/.cache to reduce Zendesk API calls.
• Complete live ticket windows are cached for 30 minutes so follow-up reports reuse the same reconciled dataset.
• Reports use Zendesk Search Count and include every matching ticket.
• Date windows with up to 1,000 tickets use the faster Search API and are reconciled by unique ticket ID.
• Larger windows are automatically split into smaller date slices so each query stays within Zendesk's 1,000-result search limit.
• Cursor-paginated Search Export is used only if a single day exceeds 1,000 tickets.
• Search Export uses Zendesk's recommended page size of 100 for reliable performance with archived tickets.
• Tickets are deduplicated by Zendesk ticket ID.
• A report is returned only when the count before export, count after export, and unique exported ticket count match.
• Report responses include report_mode, completeness, zendesk_api_requests, cache_hit, and elapsed_seconds.
• Reports include a UTC generation timestamp and note Zendesk's possible search-index delay for newly changed records.
• Use build_ticket_dashboard for multi-section dashboards instead of asking for separate reports.

Optimized Cursor Prompts

These prompts are written to minimize Zendesk API calls and OpenAI token usage. They tell Cursor to use one MCP call, avoid duplicate reports, and reuse cached ticket data.

General Management Dashboard

Use the zendesk-live MCP build_ticket_dashboard tool exactly once.
Create an executive dashboard for tickets created during the last 6 months.
Include breakdowns by Status, Priority, Type, and Created Month.
Limit each displayed section to 15 results.
Do not call list_report_fields and do not run separate reports for each section.
Show total tickets, important trends, and a concise management summary.
Present the dashboard only if completeness.status is passed.
Show expected_count, unique_ticket_count, cache_hit, and zendesk_api_requests.

Priority Over Time

Use the zendesk-live MCP build_ticket_dashboard tool exactly once.
Create a dashboard for the last 6 months using Priority and Created Month as dimensions.
Do not make separate MCP calls for Priority and Created Month.
Present the result as a priority distribution, monthly trend, key observations, and management actions.
Confirm that completeness.status is passed before presenting conclusions.

Status, Time, and Priority

Use build_ticket_dashboard exactly once for tickets created during the last 6 months.
Use the dimensions Status, Created Month, and Priority.
Use limit_per_section 20.
Do not call run_ticket_report separately for each dimension.
Summarize status distribution, monthly ticket volume, priority distribution, and notable risks.
Include the completeness reconciliation values.

Ticket Volume by Month

Use build_ticket_dashboard exactly once.
Create a ticket-volume dashboard for the last 12 months using Created Month as the primary dimension.
Also include Status and Priority.
Do not call list_report_fields or make separate report calls.
Show the busiest months and confirm the report reconciliation passed.

Agent and Time

Use the zendesk-live MCP build_ticket_dashboard tool exactly once.
Create a dashboard for the last 3 months using Assignee and Created Month as dimensions.
Use limit_per_section 20.
Do not run separate reports for each agent.
Show ticket distribution by agent, monthly volume, workload concentration, and unassigned tickets.
Do not present the report if completeness.status is not passed.

Customer and Agent

Use build_ticket_dashboard exactly once for tickets created during the last 3 months.
Use Customer and Assignee as dimensions.
Use limit_per_section 25.
Do not call run_ticket_report separately for customers and agents.
Summarize the highest-volume customers, busiest agents, workload concentration, and any unspecified values.
Show expected_count and unique_ticket_count.

One Customer Grouped by Agent

Replace XYZ with the required customer name.

Use build_ticket_dashboard exactly once.
Create a dashboard for customer XYZ covering the last 3 months.
Apply one filter: Customer contains XYZ.
Use Assignee, Status, Priority, and Created Month as dimensions.
Do not make separate MCP calls.
Show agent workload, ticket status, priority mix, monthly volume, and key observations.
Present results only when completeness.status is passed.

One Agent Grouped by Customer

Replace AGENT NAME with the required Zendesk assignee.

Use build_ticket_dashboard exactly once.
Create a dashboard for assignee Tom covering the last 3 months.
Apply one filter: Assignee equals Tom.
Use Customer, Status, Priority, and Created Month as dimensions.
Do not make separate MCP calls.
Highlight the main customers handled by this agent and the ticket status and priority mix.
Present results only when completeness.status is passed.

Version and Area for Improvement

Use the zendesk-live MCP build_ticket_dashboard tool exactly once.
Create a dashboard for tickets created during the last 3 months.
Use Version, Primary Area for Improvement, Secondary Area for Improvement, and Created Month as dimensions.
Use limit_per_section 20.
Do not run separate reports for each custom field.
Summarize the most affected versions, main improvement areas, missing field values, and monthly trends.
Include the completeness reconciliation values.

Version, Component, and Issue Type

Use build_ticket_dashboard exactly once for the last 6 months.
Use Version, Component, Issue Type, and Created Month as dimensions.
Use limit_per_section 20.
Do not call list_report_fields unless a requested field is rejected.
Identify the versions and components generating the most tickets and summarize the issue-type distribution.
Do not present conclusions unless completeness.status is passed.

Production Issues by Impact

Use build_ticket_dashboard exactly once for the last 6 months.
Apply one filter: Environment equals Production.
Use Impact, Priority, Status, Component, and Created Month as dimensions.
Use limit_per_section 20.
Do not make separate MCP calls.
Focus the summary on high-impact production risks and recurring components.
Include expected_count and unique_ticket_count.

Escalated Tickets

Use build_ticket_dashboard exactly once for the last 6 months.
Apply one filter: Escalated equals true.
Use Customer, Assignee, Priority, Status, and Primary Area for Improvement as dimensions.
Use limit_per_section 20.
Do not run separate reports.
Summarize which customers, agents, priorities, and improvement areas appear most often.
Confirm completeness.status is passed.

Open High-Priority Tickets

Use build_ticket_dashboard exactly once for the last 3 months.
Apply these filters:
- Priority in high, urgent
- Status not_in solved, closed
Use Customer, Assignee, Component, and Created Month as dimensions.
Do not call separate report tools.
Present the result as a concise operational risk dashboard.
Show the completeness reconciliation values.

Detailed Cross-Grouped Report

Use this pattern only when a combined row for each field combination is required. It uses run_ticket_report once rather than multiple calls.

Use the zendesk-live MCP run_ticket_report tool exactly once.
For the last 3 months, group tickets by Assignee and Customer together.
Use limit 50 and include_examples false.
Do not call list_report_fields unless the tool rejects a field.
Present the returned combinations in a table sorted by ticket_count.
Mention completeness.status, expected_count, unique_ticket_count, cache_hit, and zendesk_api_requests.

Filtered Cross-Grouped Report

Use run_ticket_report exactly once.
For customer XYZ during the last 3 months:
- Filter Customer contains XYZ
- Group by Primary Area for Improvement and Version together
- Use limit 40
- Keep include_examples false
Do not call any other Zendesk report tool.
Summarize the largest field combinations only if completeness.status is passed.

Prompt Guidelines

• Use build_ticket_dashboard for several independent dashboard sections.
• Use run_ticket_report only when fields must be combined into rows, such as Assignee + Customer.
• Include exactly once to discourage Cursor from issuing duplicate MCP calls.
• Avoid list_report_fields when the field names are already known.
• Ask Cursor to mention completeness.status, expected_count, unique_ticket_count, zendesk_api_requests, and cache_hit.
• Require completeness.status to be passed before the report is presented as final.
• Follow-up queries should use the same month window so the 30-minute complete ticket cache can be reused.
• Narrow the date range or add a customer, agent, status, or priority filter when faster execution is needed.