freshservice-mcp

An MCP (Model Context Protocol) server for Freshservice, letting AI assistants like Claude work with your service desk.

• Streamable HTTP transport — connect any remote-capable MCP client

• Docker-first — clone, configure, docker compose up, done

• Configured entirely via environment variables — nothing tenant-specific in the code

• Optional bearer-token auth and an optional read-only mode

Built with Python, FastAPI and FastMCP. The server grows use case by use case — tools are added iteratively rather than mirroring the whole Freshservice API.

Quickstart

Requirements: Docker with the compose plugin.

git clone <this-repo>
cd freshservice-mcp
cp .env.example .env   # then fill in your values
docker compose up -d --build

The MCP endpoint is now available at http://localhost:8000/mcp.

Related MCP server: jitbit-helpdesk-mcp

Configuration

All settings live in .env (see .env.example):

Connecting a client

Claude Code:

claude mcp add --transport http freshservice http://localhost:8000/mcp \
  --header "Authorization: Bearer <your MCP_AUTH_TOKEN>"

(omit --header if MCP_AUTH_TOKEN is empty)

Any other MCP client with Streamable HTTP support works the same way: point it at http://<host>:<port>/mcp and, if configured, send the bearer token.

Tools

Mandatory ticket fields

create_ticket deliberately creates tickets raw — no category, group or custom classification fields, just like an incoming e-mail. Your service desk triages them as usual.

If your instance marks classification fields as "required for agents when submitting the form", the API will reject such raw creates (HTTP 400 "Validation failed"), because API calls authenticate as an agent. E-mailed tickets are not affected — that requirement only applies to agents.

The fix is a Freshservice admin setting, not configuration in this server:

1. Go to Admin → (your workspace) → Service Desk Settings → Field Manager → Ticket Fields

2. Edit each affected field (e.g. Category or custom dropdowns)

3. Under the agent behavior, uncheck "Required when submitting the form" and keep "Required when closing the ticket" checked

Data quality stays enforced (nobody can close a ticket without those fields), while tickets can come in unclassified through any channel — including this MCP server.

A dedicated ticket source (e.g. a custom "AI" source, Admin → Field Manager → Ticket Fields → Source) plus FRESHSERVICE_CREATE_TICKET_SOURCE makes MCP-created tickets easy to recognize and automate on.

Security notes

• Set MCP_AUTH_TOKEN whenever the server is reachable beyond localhost (e.g. openssl rand -hex 32). Without it, anyone who can reach the port can use your Freshservice API key's permissions.

• Use a least-privilege API key. The server can never do more than the Freshservice user behind FRESHSERVICE_API_KEY is allowed to.

• FRESHSERVICE_READ_ONLY=true is a hard switch: write tools (create_ticket, reply_to_ticket, add_internal_note) are not registered on the MCP server, so a client cannot even attempt a mutation.

• For public exposure, put the server behind a TLS-terminating reverse proxy.

Development without Docker

python -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env   # fill in your values
uvicorn app.main:app --reload

Project structure

app/
├── main.py           # FastAPI app, mounts the MCP server at /mcp, /health probe
├── config.py         # settings from environment variables (pydantic-settings)
├── freshservice.py   # async Freshservice API v2 client (auth, 429 retry, errors)
└── tools/
    ├── __init__.py       # central tool registration, enforces read-only mode
    ├── tickets.py        # ticket tools (find, get, create)
    └── conversations.py  # replies and internal notes on tickets

Each new use case becomes a module under app/tools/ with a register(mcp, get_client, settings) function.

License

MIT