Freshdesk MCP

freshdesk-mcp

A self-hosted Model Context Protocol (MCP) server that exposes Freshdesk support data to MCP-compatible AI clients (Claude, Cursor, VS Code Copilot, etc.).

What it does

Connects your AI assistant directly to Freshdesk — search tickets, read conversations, extract text from attachments (including OCR for screenshots), and enrich results with status names, group names, and company IDs.

AI client → HTTPS POST /mcp → freshdesk-mcp → Freshdesk API
                                             → GCP Vision OCR (image attachments)

Available Tools

Note: find_agent and list_groups use Freshdesk admin-only endpoints (/api/v2/agents, /api/v2/groups). They work if your API key belongs to an admin account. Regular agent API keys will receive a 403.

Prerequisites

• A Freshdesk account with API access
• Docker
• A GCP project with the Vision API enabled (optional — needed for image OCR only)
• A container runtime — Cloud Run, AWS App Runner, Azure Container Apps, or plain Docker

Configuration

Deployment

Docker (any platform)

# Pull pre-built image
docker pull ghcr.io/omnom62/freshdesk-mcp:latest

# Or build from source
docker build -t freshdesk-mcp .

docker run -p 8080:8080 \
  -e MCP_TRANSPORT=http \
  -e FRESHDESK_DOMAIN=mycompany \
  -e FRESHDESK_API_KEY=your-api-key \
  -e MCP_TOKEN=your-random-secret \
  -e GCP_VISION_PROJECT=my-gcp-project \
  freshdesk-mcp

GCP Cloud Run

Build and push to Artifact Registry, then deploy:

IMAGE="<region>-docker.pkg.dev/<project>/freshdesk-mcp/freshdesk-mcp"

docker build -t ${IMAGE}:latest .
DIGEST=$(docker push ${IMAGE}:latest | grep "digest:" | awk '{print $3}')

gcloud run deploy freshdesk-mcp \
  --image ${IMAGE}@${DIGEST} \
  --region <region> \
  --platform managed \
  --allow-unauthenticated \
  --set-secrets FRESHDESK_DOMAIN=FRESHDESK_DOMAIN:latest,FRESHDESK_API_KEY=FRESHDESK_API_KEY:latest,MCP_TOKEN=MCP_TOKEN:latest \
  --set-env-vars GCP_VISION_PROJECT=<project> \
  --project <project>

Store secrets in GCP Secret Manager and grant the Cloud Run runtime service account roles/secretmanager.secretAccessor on each secret.

AWS App Runner / Azure Container Apps

Deploy the Docker image to your preferred platform. Pass the configuration variables as environment variables or secrets via your platform's secret store.

Connecting your MCP client

Once deployed, add to your MCP client config:

{
  "mcpServers": {
    "freshdesk": {
      "type": "http",
      "url": "https://your-deployment-url/mcp",
      "headers": {
        "Authorization": "Bearer your-mcp-token"
      }
    }
  }
}

Secret rotation

When rotating the Freshdesk API key:

1. Get the new key from Freshdesk → Profile → Profile Settings → API Key
2. Verify it works: curl -s -u "<new-key>:X" "https://<domain>.freshdesk.com/api/v2/tickets?per_page=1"
3. Update your secret store (e.g. GCP Secret Manager: echo -n "<new-key>" | gcloud secrets versions add FRESHDESK_API_KEY --data-file=- --project <project>)
4. Redeploy to pick up the new version

Tip: Never include :X in the stored secret value — that suffix is only used in curl Basic auth syntax.

Local development

export FRESHDESK_DOMAIN=mycompany
export FRESHDESK_API_KEY=your-api-key
export MCP_TOKEN=dev-token
export GCP_VISION_PROJECT=my-gcp-project  # optional

go run .

Server starts on port 8080. MCP endpoint: POST /mcp.

License

MIT