Freshdesk MCP Server

An MCP (Model Context Protocol) server that exposes Freshdesk helpdesk operations as tools. This allows MCP-compatible AI assistants and clients (e.g. Claude Desktop, VS Code, Cursor) to list, search, create, and manage tickets, contacts, agents, and groups directly.

---

🏆 Tool Definition Quality Score (TDQS)

This server is audited against the Tool Definition Quality Score (TDQS) framework to guarantee optimal function calling, type safety, and runtime safety for LLMs:

• Score: 5.00 / 5.00 (Tier A+)
• Behavioral Annotations (ToolAnnotations): 100% of tools specify readOnlyHint, destructiveHint, and idempotentHint metadata.
• Parameter Descriptions: 100% of tool parameters use explicit Pydantic Annotated[T, Field(description=...)] metadata.
• Operational Guidelines: Standardized docstrings detailing explicit "Use when..." context across all 34 tools.

---------------- SCORECARD METRICS ----------------
Tools Evaluated              : 34
Behavioral Annotations      : 34 / 34 (100.0%)
100% Parameter Descriptions : 34 / 34 (100.0%)
Usage Guidelines (Docstrings): 34 / 34 (100.0%)
Overall TDQS Score           : 5.00 / 5.00
TDQS Quality Tier            : Tier A+
========================================================

---

Features

• Ticket Management: Create, list, search, view, update, delete, restore tickets, add replies, add private notes, and inspect ticket fields metadata.
• Company Management: Create, list, search, view, update, and delete customer companies.
• Contact Management: Create, list, search, view, update, and delete customer contacts.
• Time Tracking: List, log, update, and delete billable/non-billable time entries on tickets.
• Solutions Knowledge Base: Browse categories, folders, articles, and search knowledge base solutions.
• Support Staff (Agents & Groups): List agents and ticket assignment groups.
• Raw API Access: Execute arbitrary REST API v2 requests (raw_api_request) supporting GET, POST, PUT, DELETE, and PATCH methods with path normalization.
• MCP Resources & Prompts: Dynamic resources (freshdesk://ticket-fields, freshdesk://agents) and workflow prompt templates (triage_ticket, draft_reply).
• Async HTTP Client: Non-blocking httpx.AsyncClient context for fast, efficient API calls.
• Tool Routing: Enable semantic search routing (TOOL_ROUTING=true) to dramatically reduce LLM context usage.
• ContextForge Gateway Support: Integrated SSE gateway to expose standard MCP servers as SSE interfaces.

---

Getting Started

Environment Variables

Variable	Description	Default
FRESHDESK_DOMAIN	The subdomain of your Freshdesk instance (e.g. yourcompany from yourcompany.freshdesk.com).	(Required)
FRESHDESK_API_KEY	Your Freshdesk API key (found under Profile Settings -> API Key).	(Required)
TOOL_ROUTING	Set to true to enable semantic tool routing (only registers 2 base tools).	false
ENABLE_CONTEXTFORGE_GATEWAY	Run the server through an SSE gateway instead of stdio.	false
GATEWAY_PORT	The port ContextForge Gateway binds to.	8000

---

Client Integration

VS Code & Antigravity IDE MCP Configuration

Create a .vscode/mcp.json file in your workspace (or add to your IDE's MCP settings):

Option 1: Docker / Podman

Podman is fully supported on Fedora/RHEL and works as a rootless drop-in replacement for Docker:

{
  "mcpServers": {
    "freshdesk": {
      "command": "podman",
      "args": [
        "run",
        "-i",
        "--rm",
        "--pull=newer",
        "-e", "FRESHDESK_DOMAIN",
        "-e", "FRESHDESK_API_KEY",
        "-e", "TOOL_ROUTING",
        "ghcr.io/jelmervdm/freshdesk-mcp:latest"
      ],
      "env": {
        "FRESHDESK_DOMAIN": "yourcompany",
        "FRESHDESK_API_KEY": "your_api_key_here",
        "TOOL_ROUTING": "false"
      }
    }
  }
}

Tip for Docker vs Podman: Simply replace "command": "podman" with "command": "docker" if using standard Docker or the podman-docker alias. Always use -i (interactive stdin) and never -t (TTY), as TTY mode appends carriage returns (\r\n) that disrupt JSON-RPC communication over stdio.

Option 2: Python / uv execution

If you prefer to run directly from source or via uv without containers:

Via uvx (from PyPI):

{
  "mcpServers": {
    "freshdesk": {
      "command": "uvx",
      "args": ["freshdesk-mcp-server"],
      "env": {
        "FRESHDESK_DOMAIN": "yourcompany",
        "FRESHDESK_API_KEY": "your_api_key_here",
        "TOOL_ROUTING": "false"
      }
    }
  }
}

Note on Tool Routing: If enabling "TOOL_ROUTING": "true", specify the [router] extra in args: ["--from", "freshdesk-mcp-server[router]", "freshdesk-mcp-server"]

Via uvx (directly from GitHub repository):

{
  "mcpServers": {
    "freshdesk": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/jelmervdm/freshdesk-mcp.git", "freshdesk-mcp-server"],
      "env": {
        "FRESHDESK_DOMAIN": "yourcompany",
        "FRESHDESK_API_KEY": "your_api_key_here",
        "TOOL_ROUTING": "false"
      }
    }
  }
}

Note on Tool Routing: If enabling "TOOL_ROUTING": "true", fetch the package with the [router] extra. Update the args array to: ["--from", "freshdesk-mcp-server[router] @ git+https://github.com/jelmervdm/freshdesk-mcp.git", "freshdesk-mcp-server"]

Via uv (local workspace directory):

{
  "mcpServers": {
    "freshdesk": {
      "command": "uv",
      "args": ["--directory", "/path/to/freshdesk-mcp", "run", "freshdesk-mcp-server"],
      "env": {
        "FRESHDESK_DOMAIN": "yourcompany",
        "FRESHDESK_API_KEY": "your_api_key_here",
        "TOOL_ROUTING": "false"
      }
    }
  }
}

Note on Tool Routing: If enabling "TOOL_ROUTING": "true", run with --extra router: ["--directory", "/path/to/freshdesk-mcp", "run", "--extra", "router", "freshdesk-mcp-server"]

Via pip / uv tool (editable or global install):

Install locally:

# Standard installation
pip install -e .
# Or via uv tool:
uv tool install freshdesk-mcp-server

# With tool routing enabled (fastembed & numpy):
pip install -e ".[router]"
# Or via uv tool:
uv tool install "freshdesk-mcp-server[router]"

Then configure the server:

{
  "mcpServers": {
    "freshdesk": {
      "command": "freshdesk-mcp-server",
      "env": {
        "FRESHDESK_DOMAIN": "yourcompany",
        "FRESHDESK_API_KEY": "your_api_key_here",
        "TOOL_ROUTING": "false"
      }
    }
  }
}

---

Semantic Tool Routing

When your MCP server has many tools, it can consume a large amount of LLM context window. To solve this, you can enable TOOL_ROUTING=true.

When enabled, only 2 tools are exposed to the LLM:

1. route_tools - Search for relevant tools using a natural language query (e.g. "find tools to reply to tickets").
2. call_routed_tool - Invoke one of the discovered/activated tools.

This uses a local CPU embedding model (fastembed with BAAI/bge-small-en-v1.5) to perform similarity search in 5-10ms.

Router Dependencies & Environment Setup

Semantic tool routing requires optional dependencies (fastembed and numpy). Ensure your setup installs these dependencies:

Environment	Command / Configuration
Docker / Podman	Pre-installed in the container image out of the box.
uvx (PyPI)	"args": ["--from", "freshdesk-mcp-server[router]", "freshdesk-mcp-server"]
uvx (GitHub)	"args": ["--from", "freshdesk-mcp-server[router] @ git+https://github.com/jelmervdm/freshdesk-mcp.git", "freshdesk-mcp-server"]
uv run (Local Workspace)	uv run --extra router freshdesk-mcp-server
uv tool install	uv tool install "freshdesk-mcp-server[router]"
pip	pip install ".[router]" or pip install "freshdesk-mcp-server[router]"

If TOOL_ROUTING=true is set without the [router] extra installed, route_tools will safely return a descriptive error message guiding the user to reinstall with the router extra.

---

Local Development

Installation

Clone the repository and install it in editable mode with development and router dependencies:

pip install -e ".[dev,router]"

Running Tests

Run the test suite using pytest:

pytest tests/ -v

Linting and Typing

Run style and static analysis checks:

flake8 src/
mypy src/

Containerization

Build the Docker image locally:

docker build -t freshdesk-mcp:latest .

Run via Docker Compose:

docker-compose up -d

---

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.