Table of Contents
- Highlights
- Quick Start
- Installation
- Configuration
- Running the Server
- Client Integration
- Tool & Prompt Catalog
- Project Layout
- Development
- Documentation
- Contributing
- Security
- License
- Acknowledgments
Highlights
Quick Start
# 1. Set credentials
export FRESHDESK_API_KEY=your_api_key
export FRESHDESK_DOMAIN=yourcompany.freshdesk.com
# 2a. Run via npx (no install needed)
npx freshdesk-mcp
# 2b. Or install globally
npm install -g freshdesk-mcp && freshdesk-mcp
# 2c. Or run as HTTP server
MCP_TRANSPORT=http PORT=3000 npx freshdesk-mcp
# → POST http://localhost:3000/mcp
# → GET http://localhost:3000/health
Installation
Requires Node.js ≥ 18 (uses the native fetch API).
From npm (recommended)
npm install -g freshdesk-mcp
freshdesk-mcp
Using npx (no install needed)
npx freshdesk-mcp
From source
git clone <this-repo>
cd freshdesk-mcp
npm install && npm run build
Build artifacts land in dist/. Runnable as node dist/index.js or via the freshdesk-mcp bin shortcut when installed globally.
Configuration
Copy .env.example to .env and load via your runner for a file-based workflow.
Full reference: docs/CONFIGURATION.md
Running the Server
stdio (local)
Default mode — reads/writes JSON-RPC on stdin/stdout. This is what Claude Desktop, Cursor, and Continue expect.
node dist/index.js
# equivalently:
MCP_TRANSPORT=stdio node dist/index.js
node dist/index.js --transport=stdio
Streamable HTTP (remote / hosted)
Conforms to the MCP Streamable HTTP transport spec (single endpoint, session-based via mcp-session-id header).
MCP_TRANSPORT=http PORT=3000 node dist/index.js
Docker
docker build -t freshdesk-mcp .
# stdio mode
docker run --rm -i \
-e FRESHDESK_API_KEY=xxx \
-e FRESHDESK_DOMAIN=acme.freshdesk.com \
freshdesk-mcp
# HTTP mode
docker run --rm -p 3000:3000 \
-e MCP_TRANSPORT=http \
-e FRESHDESK_API_KEY=xxx \
-e FRESHDESK_DOMAIN=acme.freshdesk.com \
freshdesk-mcp
Client Integration
All stdio-based MCP clients accept the same shape: a command + args + env. The examples below assume you've either installed globally (npm install -g freshdesk-mcp) or you let npx -y freshdesk-mcp fetch on demand. Replace credentials with your own.
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%/Claude/claude_desktop_config.json (Windows):
{
"mcpServers": {
"freshdesk": {
"command": "npx",
"args": ["-y", "freshdesk-mcp"],
"env": {
"FRESHDESK_API_KEY": "xxx",
"FRESHDESK_DOMAIN": "acme.freshdesk.com"
}
}
}
}
Claude Code (CLI)
claude mcp add freshdesk \
--env FRESHDESK_API_KEY=xxx \
--env FRESHDESK_DOMAIN=acme.freshdesk.com \
-- npx -y freshdesk-mcp
Or edit ~/.claude.json (project-level) → mcpServers with the same shape as Claude Desktop above.
Cursor
~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (per project):
{
"mcpServers": {
"freshdesk": {
"command": "npx",
"args": ["-y", "freshdesk-mcp"],
"env": {
"FRESHDESK_API_KEY": "xxx",
"FRESHDESK_DOMAIN": "acme.freshdesk.com"
}
}
}
}
Enable it under Settings → Cursor Settings → MCP.
OpenAI Codex CLI
~/.codex/config.toml:
[mcp_servers.freshdesk]
command = "npx"
args = ["-y", "freshdesk-mcp"]
env = { FRESHDESK_API_KEY = "xxx", FRESHDESK_DOMAIN = "acme.freshdesk.com" }
Windsurf (Codeium)
~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"freshdesk": {
"command": "npx",
"args": ["-y", "freshdesk-mcp"],
"env": {
"FRESHDESK_API_KEY": "xxx",
"FRESHDESK_DOMAIN": "acme.freshdesk.com"
}
}
}
}
Continue
~/.continue/config.json (or .continue/config.json in a workspace) under the mcpServers array:
{
"mcpServers": [
{
"name": "freshdesk",
"command": "npx",
"args": ["-y", "freshdesk-mcp"],
"env": {
"FRESHDESK_API_KEY": "xxx",
"FRESHDESK_DOMAIN": "acme.freshdesk.com"
}
}
]
}
Zed
In Zed's settings.json under context_servers:
{
"context_servers": {
"freshdesk": {
"command": {
"path": "npx",
"args": ["-y", "freshdesk-mcp"],
"env": {
"FRESHDESK_API_KEY": "xxx",
"FRESHDESK_DOMAIN": "acme.freshdesk.com"
}
}
}
}
}
Generic stdio client
Any client that follows the MCP stdio transport spec can spawn:
FRESHDESK_API_KEY=xxx FRESHDESK_DOMAIN=acme.freshdesk.com npx -y freshdesk-mcp
Remote / HTTP (Streamable HTTP)
For hosted setups (web agents, multi-user gateways), run the server in HTTP mode and point clients at the /mcp endpoint:
MCP_TRANSPORT=http PORT=3000 npx -y freshdesk-mcp
Sessions begin with POST /mcp containing an initialize body; the server returns an mcp-session-id header that the client must echo on every subsequent request. Run behind an authenticated reverse proxy — the server itself has no built-in auth.
Tool & Prompt Catalog
Full tool index with parameter signatures: docs/API.md
Zod schema reference: docs/SCHEMAS.md
Project Layout
freshdesk-mcp/
├── src/
│ ├── index.ts # Entry — picks stdio | http from env/argv
│ ├── server.ts # Builds McpServer, registers all tools + prompts
│ ├── freshdesk.ts # Fetch-based HTTP client + Link header parser
│ ├── util.ts # text(), validate(), tool() wrapper
│ ├── prompts.ts # create_ticket, create_reply prompts
│ ├── schemas/
│ │ └── index.ts # Zod schemas for every Freshdesk resource
│ └── tools/
│ ├── tickets.ts # Tickets, conversations, ticket fields/sections/forms
│ ├── attachments.ts # Attachment + inline image download (SSRF-guarded)
│ ├── contacts.ts # Contacts + contact fields
│ ├── companies.ts # Companies + company fields
│ ├── agents.ts # Agents, availability, groups, admin-groups
│ ├── canned.ts # Canned responses + folders
│ ├── solutions.ts # Categories / folders / articles
│ ├── admin_misc.ts # Skills, roles, products, BH, SLA, mailboxes,
│ │ # email configs, settings, account, threads, time entries
│ └── extras.ts # Discussions, surveys, automations, scenario,
│ # custom objects, FSM, outbound, jobs,
│ # contact activities
├── docs/
│ ├── API.md # Full tool reference
│ ├── SCHEMAS.md # Zod schema reference
│ ├── CONFIGURATION.md # Env vars + transports
│ └── DEVELOPMENT.md # Dev workflow + architecture
├── dist/ # Build output (gitignored)
├── Dockerfile
├── package.json
├── tsconfig.json
├── CHANGELOG.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
└── LICENSE
Development
npm install
npm run dev:stdio # build + run stdio mode
npm run dev:http # build + run HTTP mode on PORT (default 3000)
npm run build # type-check + emit dist/
npm run start # run from dist/
Architecture notes, adding tools, schema authoring: docs/DEVELOPMENT.md
Documentation
Upstream references
Contributing
Contributions are welcome. Read CONTRIBUTING.md before opening a PR and abide by the Code of Conduct.
Quick checklist
- Fork and branch off
main npm install && npm run build— must pass cleanly- New tools: add Zod schema → register in
src/tools/*.ts→ document indocs/API.md - Open a PR using the provided template
Security
Found a vulnerability? Do not open a public issue. Report via the channels in SECURITY.md.
This 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.
License
MIT © hashcott contributors
Acknowledgments
- The Freshdesk team for the well-documented public API
- The Model Context Protocol authors and
@modelcontextprotocol/sdkmaintainers