{"_id":"freshdesk-mcp","_rev":"3-96133c32a0467b6163876d61e5abc59c","name":"freshdesk-mcp","dist-tags":{"latest":"1.1.1"},"versions":{"1.0.0":{"name":"freshdesk-mcp","version":"1.0.0","keywords":["freshdesk","mcp","model-context-protocol","ai","llm","claude","cursor","helpdesk","typescript"],"author":{"name":"hashcott"},"license":"MIT","_id":"freshdesk-mcp@1.0.0","maintainers":[{"name":"duchanhstyle","email":"duchanhstyle@gmail.com"}],"homepage":"https://github.com/hashcott/freshdesk-mcp#readme","bugs":{"url":"https://github.com/hashcott/freshdesk-mcp/issues"},"bin":{"freshdesk-mcp":"dist/index.js"},"dist":{"shasum":"c7b6641fb0f62cfa9f91fb469d6f556556ddaa96","tarball":"https://registry.npmjs.org/freshdesk-mcp/-/freshdesk-mcp-1.0.0.tgz","fileCount":45,"integrity":"sha512-NXJHQBK8aJKoPIf8qDVBf9z45e6hCyQoc7lK1309LYeXyXKmqm+o4gIFDIsXR7egkGtTk7iPh/Ryx4BEAeOvmA==","signatures":[{"sig":"MEYCIQDGbRUXDzJS60zNh6jhETQknj3HrzSC0MRehuiYSQN9JwIhAJzU4ThK5Kv55l9Nt8+sr6C0vyRdIA1iCWrCezvzVxy6","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":454840},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"ce415326b10a94df5f347a0bce436fe4eeac42b9","scripts":{"dev":"tsc --watch","build":"tsc","start":"node dist/index.js","dev:http":"tsc && MCP_TRANSPORT=http node dist/index.js","dev:stdio":"tsc && MCP_TRANSPORT=stdio node dist/index.js","start:http":"MCP_TRANSPORT=http node dist/index.js","start:stdio":"MCP_TRANSPORT=stdio node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"duchanhstyle","email":"duchanhstyle@gmail.com"},"repository":{"url":"git+https://github.com/hashcott/freshdesk-mcp.git","type":"git"},"_npmVersion":"10.9.8","description":"MCP server for Freshdesk (TypeScript) — supports stdio and Streamable HTTP transports","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"^3.23.8","express":"^4.21.2","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.2","@types/node":"^22.10.5","@types/express":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/freshdesk-mcp_1.0.0_1780652566837_0.16151785110768047","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"freshdesk-mcp","version":"1.1.0","keywords":["freshdesk","mcp","model-context-protocol","ai","llm","claude","cursor","helpdesk","typescript"],"author":{"name":"hashcott"},"license":"MIT","_id":"freshdesk-mcp@1.1.0","maintainers":[{"name":"duchanhstyle","email":"duchanhstyle@gmail.com"}],"homepage":"https://github.com/hashcott/freshdesk-mcp#readme","bugs":{"url":"https://github.com/hashcott/freshdesk-mcp/issues"},"bin":{"freshdesk-mcp":"dist/index.js"},"dist":{"shasum":"5c8c20754561eda70161b8bffc0792c593e553ab","tarball":"https://registry.npmjs.org/freshdesk-mcp/-/freshdesk-mcp-1.1.0.tgz","fileCount":45,"integrity":"sha512-LWM0kym3p9tIkukWfbLIn6QglsfQb4LV+EhtqdRWmHdvZS0wAVQCxmBBEKYIICF7l5B177ES+a8H4HbUB+Zm2Q==","signatures":[{"sig":"MEYCIQCPRRgJlZwkTxThOqWzDOOUv5Ml0py8OSu0yPXGvgvf6AIhAI4lx69p4SE3w+2AXo6iXJ9PbAdw22JZmKWuhp64D9Kl","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/freshdesk-mcp@1.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":453735},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"edf8fe6812ab7218648e150f2ad34d8abd23a8f6","scripts":{"dev":"tsc --watch","lint":"biome check src/","build":"tsc","start":"node dist/index.js","format":"biome format --write src/","dev:http":"tsc && MCP_TRANSPORT=http node dist/index.js","lint:fix":"biome check --write src/","dev:stdio":"tsc && MCP_TRANSPORT=stdio node dist/index.js","start:http":"MCP_TRANSPORT=http node dist/index.js","start:stdio":"MCP_TRANSPORT=stdio node dist/index.js","prepublishOnly":"npm run lint && npm run build"},"_npmUser":{"name":"duchanhstyle","email":"duchanhstyle@gmail.com"},"repository":{"url":"git+https://github.com/hashcott/freshdesk-mcp.git","type":"git"},"_npmVersion":"10.9.8","description":"MCP server for Freshdesk (TypeScript) — supports stdio and Streamable HTTP transports","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"^3.23.8","express":"^4.21.2","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.2","@types/node":"^22.10.5","@biomejs/biome":"^2.4.16","@types/express":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/freshdesk-mcp_1.1.0_1780654058295_0.14600514264050268","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"freshdesk-mcp","version":"1.1.1","description":"MCP server for Freshdesk (TypeScript) — supports stdio and Streamable HTTP transports","type":"module","main":"dist/index.js","bin":{"freshdesk-mcp":"dist/index.js"},"scripts":{"build":"tsc","prepublishOnly":"npm run lint && npm run build","start":"node dist/index.js","start:stdio":"MCP_TRANSPORT=stdio node dist/index.js","start:http":"MCP_TRANSPORT=http node dist/index.js","dev":"tsc --watch","dev:stdio":"tsc && MCP_TRANSPORT=stdio node dist/index.js","dev:http":"tsc && MCP_TRANSPORT=http node dist/index.js","lint":"biome check src/","lint:fix":"biome check --write src/","format":"biome format --write src/"},"keywords":["freshdesk","mcp","model-context-protocol","ai","llm","claude","cursor","helpdesk","typescript"],"author":{"name":"hashcott"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/hashcott/freshdesk-mcp.git"},"bugs":{"url":"https://github.com/hashcott/freshdesk-mcp/issues"},"engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","express":"^4.21.2","zod":"^3.23.8"},"devDependencies":{"@biomejs/biome":"^2.4.16","@types/express":"^5.0.0","@types/node":"^22.10.5","typescript":"^5.7.2"},"_id":"freshdesk-mcp@1.1.1","gitHead":"5a13eaf83f951e6caba4d74f14fd0bd5425773b1","types":"./dist/index.d.ts","homepage":"https://github.com/hashcott/freshdesk-mcp#readme","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-ZyLywSfK4gkkGAFZoLFEc6BY5irWaBcPU3LkEGVQl1+wr30aBCIK7O8GtodhK5uH1QfSe1JS5Q1Fw39QqSXW7A==","shasum":"3968bdd48748bdca41dcb3e0d87cc37e7088868d","tarball":"https://registry.npmjs.org/freshdesk-mcp/-/freshdesk-mcp-1.1.1.tgz","fileCount":45,"unpackedSize":453583,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/freshdesk-mcp@1.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIG/mBWik8ytxNENg3vANYx7SdDBiULXeDJR1vuJSMx/BAiEAryKIVAs/q2ytZ6x2n4qbDT9uv4P+r3Vbv5dzDo36KTc="}]},"_npmUser":{"name":"duchanhstyle","email":"duchanhstyle@gmail.com"},"directories":{},"maintainers":[{"name":"duchanhstyle","email":"duchanhstyle@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/freshdesk-mcp_1.1.1_1780654770491_0.5906594598143624"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-05T09:42:46.606Z","modified":"2026-06-05T10:19:30.979Z","1.0.0":"2026-06-05T09:42:46.981Z","1.1.0":"2026-06-05T10:07:38.440Z","1.1.1":"2026-06-05T10:19:30.641Z"},"bugs":{"url":"https://github.com/hashcott/freshdesk-mcp/issues"},"author":{"name":"hashcott"},"license":"MIT","homepage":"https://github.com/hashcott/freshdesk-mcp#readme","keywords":["freshdesk","mcp","model-context-protocol","ai","llm","claude","cursor","helpdesk","typescript"],"repository":{"type":"git","url":"git+https://github.com/hashcott/freshdesk-mcp.git"},"description":"MCP server for Freshdesk (TypeScript) — supports stdio and Streamable HTTP transports","maintainers":[{"name":"duchanhstyle","email":"duchanhstyle@gmail.com"}],"readme":"

freshdesk-mcp

\n\n

\n Model Context Protocol server for the Freshdesk REST API
\n TypeScript · Zod validation · stdio & Streamable HTTP transports\n

\n\n

\n \"npm\"\n \"npm\n \"Node\"\n \"TypeScript\"\n \"MCP\n \"Tools\"\n \"License\"\n

\n\n

\n Exposes the full Freshdesk public API as MCP tools —\n compatible with Claude Desktop, Cursor, Continue, and any MCP-capable LLM client.\n

\n\n---\n\n## Table of Contents\n\n- [Highlights](#highlights)\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Running the Server](#running-the-server)\n - [stdio (local)](#stdio-local)\n - [Streamable HTTP (remote / hosted)](#streamable-http-remote--hosted)\n - [Docker](#docker)\n- [Client Integration](#client-integration)\n- [Tool & Prompt Catalog](#tool--prompt-catalog)\n- [Project Layout](#project-layout)\n- [Development](#development)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n- [Security](#security)\n- [License](#license)\n- [Acknowledgments](#acknowledgments)\n\n---\n\n## Highlights\n\n| | |\n|---|---|\n| **194 tools** | Tickets, Conversations, Contacts, Agents, Skills, Roles, Groups, Companies, Discussions, Solutions, Surveys, FSM, Time Entries, Email Configs, Products, Business Hours, SLA, Automations, Custom Objects, Canned Responses, Outbound Messages, and more |\n| **2 prompts** | `create_ticket`, `create_reply` |\n| **Strict Zod validation** | Derived from official Freshdesk docs — invalid input is rejected before hitting the API, with structured `{path, code, message}` errors |\n| **Dual transport** | `stdio` for local clients (Claude Desktop, Cursor) or `Streamable HTTP` for hosted/remote agents |\n| **Pagination** | Link-header parsing + `page` / `per_page` on every list endpoint |\n| **Single binary** | `node dist/index.js` — zero runtime dependencies on Python or Freshdesk SDKs |\n| **No deprecation warnings** | Built on `@modelcontextprotocol/sdk@^1.29.0` using `registerTool` / `registerPrompt` |\n\n---\n\n## Quick Start\n\n```bash\n# 1. Set credentials\nexport FRESHDESK_API_KEY=your_api_key\nexport FRESHDESK_DOMAIN=yourcompany.freshdesk.com\n\n# 2a. Run via npx (no install needed)\nnpx freshdesk-mcp\n\n# 2b. Or install globally\nnpm install -g freshdesk-mcp && freshdesk-mcp\n\n# 2c. Or run as HTTP server\nMCP_TRANSPORT=http PORT=3000 npx freshdesk-mcp\n# → POST http://localhost:3000/mcp\n# → GET http://localhost:3000/health\n```\n\n---\n\n## Installation\n\nRequires **Node.js ≥ 18** (uses the native `fetch` API).\n\n**From npm (recommended)**\n\n```bash\nnpm install -g freshdesk-mcp\nfreshdesk-mcp\n```\n\n**Using npx (no install needed)**\n\n```bash\nnpx freshdesk-mcp\n```\n\n**From source**\n\n```bash\ngit clone \ncd freshdesk-mcp\nnpm install && npm run build\n```\n\nBuild artifacts land in `dist/`. Runnable as `node dist/index.js` or via the `freshdesk-mcp` bin shortcut when installed globally.\n\n---\n\n## Configuration\n\n| Env Var | Required | Default | Description |\n|---|---|---|---|\n| `FRESHDESK_API_KEY` | ✅ | — | API key from your Freshdesk profile → **Profile → API Key** |\n| `FRESHDESK_DOMAIN` | ✅ | — | Account domain, e.g. `acme.freshdesk.com` (no scheme, no trailing `/`) |\n| `MCP_TRANSPORT` | ❌ | `stdio` | `stdio` or `http` |\n| `PORT` | ❌ | `3000` | HTTP listen port (only when `MCP_TRANSPORT=http`) |\n\nCopy `.env.example` to `.env` and load via your runner for a file-based workflow.\n\n> Full reference: **[docs/CONFIGURATION.md](docs/CONFIGURATION.md)**\n\n---\n\n## Running the Server\n\n### stdio (local)\n\nDefault mode — reads/writes JSON-RPC on stdin/stdout. This is what Claude Desktop, Cursor, and Continue expect.\n\n```bash\nnode dist/index.js\n# equivalently:\nMCP_TRANSPORT=stdio node dist/index.js\nnode dist/index.js --transport=stdio\n```\n\n### Streamable HTTP (remote / hosted)\n\nConforms to the MCP **Streamable HTTP** transport spec (single endpoint, session-based via `mcp-session-id` header).\n\n```bash\nMCP_TRANSPORT=http PORT=3000 node dist/index.js\n```\n\n| Method | Path | Purpose |\n|---|---|---|\n| `POST` | `/mcp` | Initialize a session or send a JSON-RPC request |\n| `GET` | `/mcp` | SSE stream for server-initiated messages (per-session) |\n| `DELETE` | `/mcp` | Terminate a session |\n| `GET` | `/health` | Liveness probe — `{ status: \"ok\", ... }` |\n\n### Docker\n\n```bash\ndocker build -t freshdesk-mcp .\n\n# stdio mode\ndocker run --rm -i \\\n -e FRESHDESK_API_KEY=xxx \\\n -e FRESHDESK_DOMAIN=acme.freshdesk.com \\\n freshdesk-mcp\n\n# HTTP mode\ndocker run --rm -p 3000:3000 \\\n -e MCP_TRANSPORT=http \\\n -e FRESHDESK_API_KEY=xxx \\\n -e FRESHDESK_DOMAIN=acme.freshdesk.com \\\n freshdesk-mcp\n```\n\n---\n\n## Client Integration\n\n### Claude Desktop / Claude Code\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):\n\n```json\n{\n \"mcpServers\": {\n \"freshdesk\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"freshdesk-mcp\"],\n \"env\": {\n \"FRESHDESK_API_KEY\": \"xxx\",\n \"FRESHDESK_DOMAIN\": \"acme.freshdesk.com\"\n }\n }\n }\n}\n```\n\nIf installed globally via `npm install -g freshdesk-mcp`:\n\n```json\n{\n \"mcpServers\": {\n \"freshdesk\": {\n \"command\": \"freshdesk-mcp\",\n \"env\": {\n \"FRESHDESK_API_KEY\": \"xxx\",\n \"FRESHDESK_DOMAIN\": \"acme.freshdesk.com\"\n }\n }\n }\n}\n```\n\n### Cursor / Continue / other stdio clients\n\nSame `command` + `env` shape — see your client's MCP server config docs.\n\n### Remote / HTTP\n\nPoint your client at `http://your-host:3000/mcp` (or behind a reverse proxy). Sessions are created on the first `POST /mcp` with an `initialize` body; the server returns an `mcp-session-id` header that the client must echo on every subsequent request.\n\n---\n\n## Tool & Prompt Catalog\n\n> Full tool index with parameter signatures: **[docs/API.md](docs/API.md)**\n\n| Group | Tools | Highlights |\n|---|---|---|\n| Tickets | 30 | CRUD, bulk_*, restore, archived, merge, forward, summary, satisfaction, time entries |\n| Conversations | 6 | Reply, note, update, delete, reply_to_forward |\n| Contacts | 17 | CRUD, merge, make_agent, restore, hard_delete, invite, contact fields CRUD |\n| Companies | 13 | CRUD, search, company contacts, company fields CRUD |\n| Agents + Groups | 18 | Agents CRUD + `me` + bulk; Groups CRUD; Admin-Groups CRUD |\n| Solutions | 16 | Categories / folders / articles CRUD + search |\n| Discussions | 19 | Forum categories / forums / topics / comments CRUD |\n| Time Entries | 6 | CRUD + toggle timer |\n| Threads | 9 | Collaboration threads + messages CRUD |\n| Automations | 5 | Rules CRUD per type |\n| FSM | 8 | Service tasks, appointments, business calendars |\n| Custom Objects | 7 | Schemas + records CRUD |\n| ...and more | — | Skills, Roles, Products, Business Hours, SLA, Email Configs, Mailboxes, Settings, Account, Jobs, Surveys, Satisfaction Ratings, Outbound, Availability, Omnichannel |\n\nZod schema reference: **[docs/SCHEMAS.md](docs/SCHEMAS.md)**\n\n---\n\n## Project Layout\n\n```\nfreshdesk-mcp/\n├── src/\n│ ├── index.ts # Entry — picks stdio | http from env/argv\n│ ├── server.ts # Builds McpServer, registers all tools + prompts\n│ ├── freshdesk.ts # Fetch-based HTTP client + Link header parser\n│ ├── util.ts # text(), validate(), tool() wrapper\n│ ├── prompts.ts # create_ticket, create_reply prompts\n│ ├── schemas/\n│ │ └── index.ts # Zod schemas for every Freshdesk resource\n│ └── tools/\n│ ├── tickets.ts # Tickets + conversations + ticket fields\n│ ├── contacts.ts # Contacts + contact fields\n│ ├── companies.ts # Companies + company fields\n│ ├── agents.ts # Agents + groups + admin-groups\n│ ├── canned.ts # Canned responses + folders\n│ ├── solutions.ts # Categories / folders / articles\n│ ├── admin_misc.ts # Skills, roles, products, BH, SLA, mailboxes,\n│ │ # email configs, settings, account, threads, time entries\n│ └── extras.ts # Discussions, surveys, automations, scenario,\n│ # custom objects, FSM, outbound, jobs,\n│ # availability, omnichannel\n├── docs/\n│ ├── API.md # Full tool reference\n│ ├── SCHEMAS.md # Zod schema reference\n│ ├── CONFIGURATION.md # Env vars + transports\n│ └── DEVELOPMENT.md # Dev workflow + architecture\n├── dist/ # Build output (gitignored)\n├── Dockerfile\n├── package.json\n├── tsconfig.json\n├── CHANGELOG.md\n├── CONTRIBUTING.md\n├── CODE_OF_CONDUCT.md\n├── SECURITY.md\n└── LICENSE\n```\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm run dev:stdio # build + run stdio mode\nnpm run dev:http # build + run HTTP mode on PORT (default 3000)\nnpm run build # type-check + emit dist/\nnpm run start # run from dist/\n```\n\n> Architecture notes, adding tools, schema authoring: **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)**\n\n---\n\n## Documentation\n\n| Doc | Purpose |\n|---|---|\n| [docs/API.md](docs/API.md) | Complete tool index, parameter signatures, return shapes |\n| [docs/SCHEMAS.md](docs/SCHEMAS.md) | Zod schema reference for every Freshdesk resource |\n| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | Env vars, transports, runtime tuning |\n| [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | Architecture, adding tools, schema authoring |\n| [CHANGELOG.md](CHANGELOG.md) | Version history |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute |\n| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community guidelines |\n| [SECURITY.md](SECURITY.md) | Reporting vulnerabilities |\n\n**Upstream references**\n\n- [Freshdesk API](https://developers.freshdesk.com/api/)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)\n\n---\n\n## Contributing\n\nContributions are welcome. Read **[CONTRIBUTING.md](CONTRIBUTING.md)** before opening a PR and abide by the **[Code of Conduct](CODE_OF_CONDUCT.md)**.\n\n**Quick checklist**\n\n1. Fork and branch off `main`\n2. `npm install && npm run build` — must pass cleanly\n3. New tools: add Zod schema → register in `src/tools/*.ts` → document in `docs/API.md`\n4. Open a PR using the provided template\n\n---\n\n## Security\n\nFound a vulnerability? **Do not open a public issue.** Report via the channels in **[SECURITY.md](SECURITY.md)**.\n\nThis server transmits your Freshdesk API key to `*.freshdesk.com` over HTTPS only. The key is never logged. Run the HTTP transport behind an authenticated reverse proxy when exposing it beyond `localhost`.\n\n---\n\n## License\n\n[MIT](LICENSE) © hashcott contributors\n\n---\n\n## Acknowledgments\n\n- The Freshdesk team for the well-documented public API\n- The Model Context Protocol authors and `@modelcontextprotocol/sdk` maintainers\n","readmeFilename":"README.md"}