Freshdesk MCP

English · Français

A self-hosted Model Context Protocol server by BoucheCousue for Freshdesk: agent-specific access, ticket context, customer history, controlled ticket actions and optional local semantic search.

Each user connects their own Freshdesk tenant and personal API key through the server's OAuth flow. Freshdesk calls use that agent's native permissions. This is a community project, not an official Freshworks product.

Features

• 24 MCP tools for tickets, contacts, companies, agents, groups, knowledge and semantic search.

• OAuth authorization code + PKCE S256, client metadata discovery, dynamic registration and rotating refresh tokens.

• API keys encrypted with AES-256-GCM; local SQLite storage.

• Ticket Cockpit interface for MCP Apps clients, with conversations, SLA, ownership and attachments metadata.

• Writes use an immutable, expiring preview, interactive confirmation, a single-use intent and readback verification. Uncertain writes are never retried automatically.

• Optional semantic search over locally indexed history, with fresh access checks before returning evidence.

The implementation targets MCP 2026-07-28 and ChatGPT. Client support for OAuth, MCP Apps and interactive confirmation varies; verify your intended client. Connection pages and parts of the interface currently use French; the documentation is available in both languages.

Related MCP server: FS_MCP_thin

Quick start

Use Node.js 22 or 24 and npm. Install and run with the same Node major version because SQLite uses a native module.

git clone https://github.com/bouchecousue/freshdesk-mcp.git
cd freshdesk-mcp
npm ci
cp .env.example .env
chmod 600 .env
npm run --silent generate-master-key

Copy the generated value into FRESHDESK_MCP_MASTER_KEY in your local .env. Then:

npm run build
node --env-file=.env dist/src/index.js

In another terminal:

curl -fsS http://127.0.0.1:8788/health
curl -i http://127.0.0.1:8788/mcp

The health route returns service status; an unauthenticated /mcp request returns 401 with OAuth discovery information. This does not yet prove Freshdesk connectivity: connect an agent and call freshdesk_health.

For a remote client, publish through your own HTTPS reverse proxy or tunnel and set NODE_ENV=production and PUBLIC_URL=https://mcp.example.com. The endpoint is https://mcp.example.com/mcp. See the deployment guide before exposing the service.

Documentation

Development

npm ci
npm run check
node --env-file=.env --import tsx --watch src/index.ts

check runs TypeScript checking, mocked tests and a production build. Tests do not require a real Freshdesk account or production secrets. GitHub Actions runs checks on Node 22 and 24 and scans Git history for secrets.

This repository contains source code, synthetic tests and generic examples. It does not include credentials, customer exports, runtime databases, logs or private deployment configuration. Runtime files belong outside Git; see CONTRIBUTING.md.

License and references

MIT, copyright BoucheCousue. Third-party dependencies and optional embedding models retain their own licenses; model weights are not included.

Freshdesk API · MCP specification · Connecting MCP servers in ChatGPT