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.

Configuration

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

Variable	Required	Default	Description
FRESHSERVICE_DOMAIN	yes	–	Your tenant, e.g. yourcompany.freshservice.com (bare yourcompany works too)
FRESHSERVICE_API_KEY	yes	–	API key of the Freshservice user the server acts as (Profile Settings → API Key). All tool calls run with this user's permissions
FRESHSERVICE_READ_ONLY	no	false	true registers no write tools at all — the server can only read
FRESHSERVICE_CREATE_TICKET_SOURCE	no	1	Source code stamped on created tickets (1=Email, 2=Portal, 3=Phone, 9=Walk-up; see GET /api/v2/ticket_form_fields for your instance's values, including custom sources)
MCP_AUTH_TOKEN	no	empty	If set, clients must send Authorization: Bearer <token>. Empty = unauthenticated
MCP_PORT	no	8000	Host port the server is published on

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

Tool	Description
find_tickets_by_requester_email	Find tickets by the requester's email address. By default only open tickets (status Open or Pending); only_open=false includes resolved/closed. Paginated, 30 per page
get_ticket	Full details of a single ticket by ID, including the description text
create_ticket	Create a ticket on behalf of a requester (by email) — subject + plain-text body, no classification fields, source configurable. Hidden in read-only mode
reply_to_ticket	Send a reply to the requester on an existing ticket — visible to the requester, notifies them. Hidden in read-only mode
add_internal_note	Add a private note to a ticket — agents only, requester is not notified, ticket stays unchanged. Hidden in read-only mode

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