{
  "markdown": "# Freshdesk MCP Server\n\n[![Build Status](https://github.com/WYRE-AI/freshdesk-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/WYRE-AI/freshdesk-mcp/actions/workflows/release.yml)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides AI assistants with structured access to the [Freshdesk](https://www.freshdesk.com) customer support platform — tickets, contacts, companies, agents, groups, the knowledge base, and SLA/business-hours configuration.\n\n> **Note:** This project is maintained by [Wyre Technology](https://github.com/WYRE-AI). It wraps the published [`@wyre-technology/node-freshdesk`](https://github.com/WYRE-AI/node-freshdesk) SDK.\n\n## Quick Start\n\nThe primary deployment is through the **WYRE MCP Gateway**, which hosts the containerized server and injects per-request credentials. To run it yourself:\n\n**Claude Code (CLI):**\n\n```bash\nclaude mcp add freshdesk-mcp \\\n  -e FRESHDESK_DOMAIN=your-subdomain \\\n  -e FRESHDESK_API_KEY=your-api-key \\\n  -- npx -y github:WYRE-AI/freshdesk-mcp\n```\n\n`FRESHDESK_DOMAIN` is the part before `.freshdesk.com` (for `https://acme.freshdesk.com` it is `acme`). Find your `FRESHDESK_API_KEY` in the Freshdesk portal under **Profile Settings**.\n\n## Features\n\n- **🔌 MCP Protocol Compliance**: Tools, prompts, and elicitation support\n- **🎫 Full Helpdesk Coverage**: Tickets, contacts, companies, agents, groups, solutions, SLA policies, business hours, and canned responses\n- **🌳 Decision-Tree Navigation**: Start at `freshdesk_navigate`, enter a domain to reveal its tools, and `freshdesk_back` to return — keeping the tool list small and focused\n- **⚠️ Destructive-Action Guardrails**: Irreversible and high-impact tools are clearly flagged and confirmed via elicitation before they run\n- **🔒 Secure Authentication**: HTTP Basic Auth with your Freshdesk API key (domain + key)\n- **🌐 Dual Transport**: stdio (local) and Streamable HTTP (remote/Docker/gateway)\n- **🐳 Docker Ready**: Containerized deployment with HTTP transport and health checks\n\n## Connecting via the Gateway\n\nWhen `AUTH_MODE=gateway`, the server reads credentials from request headers injected by the WYRE MCP Gateway:\n\n| Header | Maps to | Description |\n|--------|---------|-------------|\n| `x-freshdesk-domain` | `FRESHDESK_DOMAIN` | Freshdesk account subdomain |\n| `x-freshdesk-api-key` | `FRESHDESK_API_KEY` | Freshdesk API key |\n\nEach request is stateless: the gateway provides the credentials, the server rebuilds its Freshdesk client, and tool discovery (`tools/list`) works even before credentials are present.\n\n## Configuration\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `FRESHDESK_DOMAIN` | Account subdomain (before `.freshdesk.com`) | — |\n| `FRESHDESK_API_KEY` | Freshdesk API key | — |\n| `MCP_TRANSPORT` | Transport mode (`stdio` or `http`) | `stdio` |\n| `MCP_HTTP_PORT` | HTTP server port | `8080` |\n| `AUTH_MODE` | Auth mode (`env` or `gateway`) | `env` |\n| `LOG_LEVEL` | Log level (`debug`, `info`, `warn`, `error`) | `info` |\n\n## Tool Overview\n\nThe server uses **decision-tree navigation**. At the top level you see only `freshdesk_navigate`, `freshdesk_back`, and `freshdesk_status`. Call `freshdesk_navigate` with a domain to reveal that domain's tools; call `freshdesk_back` to return to the top.\n\n| Domain | Tools |\n|--------|-------|\n| **tickets** | search, list, get, create, update, reply, add_note, list_conversations, update_conversation, delete\\*, delete_conversation\\* |\n| **contacts** | search, list, get, create, update, autocomplete, make_agent†, restore, send_invite, merge†, soft_delete†, hard_delete\\* |\n| **companies** | search, list, get, create, update, autocomplete, delete\\* |\n| **agents** | list, get, me, create, update, delete\\* |\n| **groups** | list, get, create, update, delete\\* |\n| **solutions** | categories / folders / articles: list, get, create, update, delete\\* |\n| **sla-business** | SLA policies (list, create, update), business hours (list, get), canned responses (list_folders, get_folder, list_responses) |\n\n`*` = **Tier A** (irreversible delete) — flagged `⚠ DESTRUCTIVE — IRREVERSIBLE`, requires confirmation.\n`†` = **Tier B** (high-impact reversible) — flagged `⚠ HIGH-IMPACT`, requires confirmation.\n\nRead tools (search/list/get/autocomplete/status) carry no warning and are marked read-only.\n\n`freshdesk_status` performs a live connectivity check by calling `agents/me`.\n\n## Docker Deployment\n\nSee [docker-compose.yml](docker-compose.yml). Copy `.env.example` to `.env` and fill in your credentials:\n\n```bash\ncp .env.example .env\n# Edit .env: FRESHDESK_DOMAIN and FRESHDESK_API_KEY\ndocker compose up -d\n```\n\nThe build installs `@wyre-technology/node-freshdesk` from GitHub Packages via a\nBuildKit npmrc secret (never baked into a layer):\n\n```bash\nprintf '@wyre-ai:registry=https://npm.pkg.github.com\\n@wyre-technology:registry=https://npm.pkg.github.com\\n//npm.pkg.github.com/:_authToken=%s\\n' \"$(gh auth token)\" > /tmp/.npmrc\ndocker build --secret id=npmrc,src=/tmp/.npmrc -t freshdesk-mcp .\nrm /tmp/.npmrc\n```\n\n## Development\n\n```bash\nexport NODE_AUTH_TOKEN=$(gh auth token)   # to install @wyre-technology/node-freshdesk\nnpm install\nnpm run build       # Build the project\nnpm run dev         # Watch mode\nnpm run test        # Run tests\nnpm run lint        # Type-check\nnpm run clean       # Remove dist/\n```\n\n## Testing\n\n```bash\nnpm test            # Run test suite\nnpm run test:watch  # Watch mode\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nApache 2.0 — Copyright WYRE Technology\n",
  "bytes": 5810,
  "sha": "9e364f2af0f6b660e813cc9f04fdf2a3fdb26a3ee352a8c50751e14eff7bf0e3",
  "repo_slug": "wyre-technology/freshdesk-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_wyre_technology_freshdesk_mcp_ec3db10b/readme"
}