Freshdesk

Table of Contents

• Highlights
• Quick Start
• Installation
• Configuration
• Running the Server
  • stdio (local)
  • Streamable HTTP (remote / hosted)
  • Docker
• 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

• Freshdesk API
• Model Context Protocol
• MCP TypeScript SDK

Contributing

Contributions are welcome. Read CONTRIBUTING.md before opening a PR and abide by the Code of Conduct.

Quick checklist

1. Fork and branch off main
2. npm install && npm run build — must pass cleanly
3. New tools: add Zod schema → register in src/tools/*.ts → document in docs/API.md
4. 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/sdk maintainers