Freshservice MCP server

Freshservice MCP Server

A configurable MCP server for the Freshservice REST API with permission-based tool gating.

Freshservice only provides a single API key per account with no scoping. This server addresses that by introducing a FRESHSERVICE_MODE environment variable that controls which tools are exposed. Blocked tools are excluded at registration time, so the LLM never sees them.

Permission Modes

Mode	Tools	Description
read	54	List, view, filter, search across all modules. File search. No modifications.
standard	81	Read + create/update tickets, changes, approvals, service requests, attachments, time entries. No deletes, no agent/group admin.
full	97	Standard + products, requesters, solution articles, delete notes/tasks/time entries. No agent creation, no ticket/change deletion.
admin	107	Everything. Create/delete agents, groups, tickets, changes, attachments.

Default mode is read.

Setup

Prerequisites

• uv (recommended) — manages Python and dependencies for you, with hash-verified installs
  • or Python 3.11+ with pip
• A Freshservice account with API access enabled

Getting Your Freshservice API Key

1. Log into your Freshservice portal as an agent
2. Click your profile picture in the top-right corner
3. Go to Profile Settings
4. Your API key is shown in the right sidebar under Your API Key
5. Copy it — you'll need it for configuration below

Note: Freshservice provides a single API key per agent with no scoping. This is why the server has permission modes — so you can limit what the LLM can do, even though the API key itself has full access.

Environment Variables

Variable	Required	Description
FRESHSERVICE_DOMAIN	Yes	Your Freshservice domain (e.g. yourcompany.freshservice.com)
FRESHSERVICE_APIKEY	Yes	Your Freshservice API key
FRESHSERVICE_MODE	No	Permission mode: read, standard, full, or admin. Default: read
FRESHSERVICE_CACHE_TTL	No	Cache lifetime in seconds for schema/reference data. Default: 3600 (1 hour). Set to 0 to disable caching.
FRESHSERVICE_FILE_SEARCH_PATHS	No	Semicolon-separated list of directories the find_file tool can search (e.g. C:\Users\me\Docs;C:\Exports). Required for file discovery.
FRESHSERVICE_AUDIT_LOG	No	Path to a JSON-lines audit log (e.g. C:\logs\freshservice-audit.jsonl). Every tool call is logged with sanitized arguments, success/error state, and timing. Disabled when unset.

Install

Option A — uv (recommended). No install step at all: uvx fetches the package from PyPI on first run and caches it. Pin the version so upgrades are deliberate:

uvx node804-freshservice-mcp==1.4.1

Option B — pip:

pip install node804-freshservice-mcp

Option C — from source (development):

git clone <this-repo>
cd node804-freshservice-mcp
uv sync          # or: pip install -e ".[dev]"

Each option provides the node804-freshservice-mcp command and the node804_freshservice_mcp Python module.

Claude Desktop

1. Open your Claude Desktop config file:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

   Or open it from Claude Desktop: Settings → Developer → Edit Config.

2. Add a freshservice entry under mcpServers (create the file if it doesn't exist), using one of the options below. Every value in env must be a string, including FRESHSERVICE_CACHE_TTL.

3. Fully quit Claude Desktop (including from the system tray / menu bar) and reopen it. The server starts automatically when Claude needs it.

Option A — uvx (recommended). Nothing to install beyond uv. The package is fetched from PyPI on first launch and cached; change the pinned version to upgrade.

{
  "mcpServers": {
    "freshservice": {
      "command": "uvx",
      "args": ["node804-freshservice-mcp==1.4.1"],
      "env": {
        "FRESHSERVICE_APIKEY": "your_api_key",
        "FRESHSERVICE_DOMAIN": "yourcompany.freshservice.com",
        "FRESHSERVICE_MODE": "standard",
        "FRESHSERVICE_CACHE_TTL": "3600"
      }
    }
  }
}

Claude Desktop does not always inherit your shell's PATH. If it reports that uvx can't be found, use the full path to the executable: run where uvx (Windows) or which uvx (macOS) and put the result in command, e.g. "C:\\Users\\you\\.local\\bin\\uvx.exe" or "/Users/you/.local/bin/uvx".

Option B — pip. Install the package first, then point Claude Desktop at the Python interpreter you installed it into:

pip install node804-freshservice-mcp==1.4.1

{
  "mcpServers": {
    "freshservice": {
      "command": "python",
      "args": ["-m", "node804_freshservice_mcp.server"],
      "env": {
        "FRESHSERVICE_APIKEY": "your_api_key",
        "FRESHSERVICE_DOMAIN": "yourcompany.freshservice.com",
        "FRESHSERVICE_MODE": "standard",
        "FRESHSERVICE_CACHE_TTL": "3600"
      }
    }
  }
}

Use the full path to the interpreter if python on Claude Desktop's PATH isn't the one that has the package (common with virtual environments, the Windows Store Python, or multiple installs). Find it with python -c "import sys; print(sys.executable)". Alternatively, set "command" to the full path of the node804-freshservice-mcp script pip installed (in the interpreter's Scripts\ folder on Windows or bin/ on macOS) and drop args.

To upgrade a pip install: pip install -U node804-freshservice-mcp, then restart Claude Desktop.

Using a .env file instead of inline env values:

If you'd rather keep credentials out of claude_desktop_config.json, create a .env file in the repo root (see .env.example) and use cwd to point the server at it:

cp .env.example .env   # edit with your credentials

{
  "mcpServers": {
    "node804-freshservice-mcp": {
      "command": "uvx",
      "args": ["node804-freshservice-mcp==1.4.1"],
      "cwd": "/path/to/node804-freshservice-mcp"
    }
  }
}

The server calls load_dotenv() on startup, which reads .env from the working directory. The cwd field tells Claude Desktop to start the server in the repo root where that file lives.

Claude Code (plugin)

This repo is also a Claude Code plugin marketplace. The plugin bundles the MCP server and a skill that teaches Claude which Freshservice tools to reach for. On enable, Claude Code prompts for your domain, API key (stored in the OS credential store), permission mode, and the optional settings.

claude plugin marketplace add Node804/node804-freshservice-mcp

claude plugin install freshservice@node804

Or from inside a session: /plugin marketplace add Node804/node804-freshservice-mcp, then /plugin install freshservice@node804. Requires uv on your PATH. To change settings later, run claude plugin configure freshservice@node804.

Claude Code (CLI)

claude mcp add node804-freshservice-mcp \
  -e FRESHSERVICE_APIKEY=your_api_key \
  -e FRESHSERVICE_DOMAIN=yourcompany.freshservice.com \
  -e FRESHSERVICE_MODE=standard \
  -- uvx node804-freshservice-mcp==1.4.1

To verify it was added:

claude mcp list

ChatGPT

ChatGPT desktop app (recommended). The desktop app can launch local stdio servers directly, the same way Claude Desktop does. Open the app's Connect to a custom MCP form (Developer mode / custom connectors in settings) and fill it in:

Field	Value
Name	freshservice
Type	STDIO
Command to launch	uvx (or the full path from where uvx / which uvx if the app can't find it)
Arguments	node804-freshservice-mcp==1.4.1
Environment variables	FRESHSERVICE_APIKEY, FRESHSERVICE_DOMAIN, FRESHSERVICE_MODE, plus any optional ones from Environment Variables

For a pip install, set Command to launch to the full path of your Python interpreter and add two arguments: -m and node804_freshservice_mcp.server. Put each argument in its own box (+ Add argument), not space-separated in one.

If the variables are already set in your user environment, you can list their names under Environment variable passthrough instead of typing the values into the form.

ChatGPT on the web. chatgpt.com can only reach remote MCP servers over HTTPS, so it cannot launch this stdio server. You'd need a stdio-to-HTTP bridge such as mcp-proxy plus a public HTTPS tunnel. That bridge has no authentication: anyone who learns the URL can use every tool in your mode with your Freshservice API key. Use the desktop app instead unless you can put real authentication (e.g. Cloudflare Access) in front of it, and keep it in read mode.

OpenAI Codex (CLI / IDE extension) does support local stdio servers, so no bridge is needed:

codex mcp add freshservice \
  --env FRESHSERVICE_APIKEY=your_api_key \
  --env FRESHSERVICE_DOMAIN=yourcompany.freshservice.com \
  --env FRESHSERVICE_MODE=standard \
  -- uvx node804-freshservice-mcp==1.4.1

Or add it to ~/.codex/config.toml by hand:

[mcp_servers.freshservice]
command = "uvx"
args = ["node804-freshservice-mcp==1.4.1"]

[mcp_servers.freshservice.env]
FRESHSERVICE_APIKEY = "your_api_key"
FRESHSERVICE_DOMAIN = "yourcompany.freshservice.com"
FRESHSERVICE_MODE = "standard"

Installing the Skill

The repo ships a skill, skills/freshservice/SKILL.md, that teaches the model which tools to call: convenience tools like get_my_tickets, service-request items, filter query syntax, when to confirm before emailing a requester, and pagination. The server works without it, but the model makes fewer calls and fewer mistakes with it.

Claude Code plugin: nothing to do. The skill installs with the plugin (see Claude Code (plugin)).

Claude Code without the plugin: copy the folder into your personal skills directory:

mkdir -p ~/.claude/skills && cp -r skills/freshservice ~/.claude/skills/

New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills" | Out-Null
Copy-Item -Recurse skills\freshservice "$env:USERPROFILE\.claude\skills\"

Or into .claude/skills/ inside a project to scope it to that project.

Claude Desktop / claude.ai: zip the freshservice folder (the zip must contain freshservice/SKILL.md) and upload it under Settings → Capabilities → Skills. Skills must be enabled for your plan or organization.

Compress-Archive -Path skills\freshservice -DestinationPath freshservice-skill.zip

ChatGPT / Codex: Codex reads skills from ~/.codex/skills/, so copy the freshservice folder there. In the ChatGPT app, paste the body of SKILL.md (everything below the --- front matter) into a Project's instructions or your custom instructions.

After upgrading the server, update the skill too. It describes tool behavior for the matching version.

Verifying It Works

Once connected, ask your LLM:

• "What's my access level?" → calls server_status, shows the mode, tool count, and rate-limit info
• "Who am I in Freshservice?" → calls get_current_agent, confirms the API key is valid and returns your agent profile

If either fails, check the Troubleshooting section below.

Project Structure

src/node804_freshservice_mcp/
  __init__.py           # Package marker + version
  server.py             # FastMCP instance, conditional_tool decorator, main()
  config.py             # Permission modes, tool hierarchy, mode summary
  client.py             # Shared httpx client, rate-limit transport, response cache, auth
  models.py             # Enums (TicketSource, ChangeStatus, ...) + Pydantic models
  tools/
    __init__.py          # Imports all tool modules to trigger registration
    tickets.py           # 24 tools  - tickets, conversations, attachments, time entries
    changes.py           # 33 tools  - changes, approvals, notes, tasks, time entries
    service_catalog.py   # 3 tools   - service items + requests
    products.py          # 4 tools   - product CRUD
    requesters.py        # 6 tools   - requester CRUD + fields
    agents.py            # 7 tools   - current agent, agent CRUD + fields
    groups.py            # 10 tools  - agent groups + requester groups
    canned_responses.py  # 4 tools   - canned responses + folders
    workspaces.py        # 2 tools   - workspace listing
    solutions.py         # 13 tools  - KB categories, folders, articles
    files.py             # 1 tool    - local file search for attachment discovery

Mode Details

read (default)

Safe for anyone who needs to look up ticket info, check change status, or search the knowledge base. Cannot modify anything.

Includes: get/list/filter/view operations for tickets, changes, agents, requesters, groups, products, service catalog, canned responses, workspaces, and solution articles.

standard

Day-to-day IT work. Create and update tickets, manage changes through their lifecycle, send replies, add notes, handle approvals. Cannot delete anything or manage agents/groups.

Includes everything in read plus: create/update tickets, create/update changes, close changes, ticket replies and notes, attachments, change tasks/notes/time entries, approval management, service requests.

full

Adds content management and requester administration. For senior staff who need to manage the knowledge base and requester records.

Includes everything in standard plus: create/update products, create/update requesters, solution article/folder/category management, delete change notes/tasks/time entries, requester group membership.

admin

Full access to everything, including destructive operations. Only use this if you specifically need to create agents, delete tickets or changes, or manage group structures.

Includes everything in full plus: delete tickets, delete changes, create/update agents, create/update agent groups, create/update requester groups.

Attachments

The server provides attachment tools for uploading, listing, and deleting files on tickets.

Finding files

Use find_file to search for files on the local filesystem by partial name or glob pattern before attaching them. This is the recommended first step when a user asks to find, locate, or attach files from their system — for example, asking to "attach the Q4 report" will find Q4_Report.pdf in any configured search directory.

Searches are restricted to directories listed in the FRESHSERVICE_FILE_SEARCH_PATHS environment variable (semicolon-separated). Matching is case-insensitive and supports partial names (report), glob patterns (*.pdf), and recursive subdirectory search.

Uploading

Use add_ticket_attachment, add_note_attachment, and add_reply_attachment to upload files. These tools take an absolute file path on the MCP server's local filesystem, read the file, detect MIME type, and upload it via multipart form-data.

Note: The MCP server must have filesystem access to the file being attached. These tools are designed for scenarios where the MCP client (e.g. Claude Code) runs on the same machine or can write files to a path the server can read.

Listing and deleting

• list_ticket_attachments — list all attachments on a ticket (read mode)
• delete_ticket_attachment / delete_conversation_attachment — remove attachments (admin mode)

Freshservice limit: The total size of all attachments on a single ticket cannot exceed 40 MB.

Agent Signatures

The send_ticket_reply and add_reply_attachment tools automatically append the current agent's HTML signature to every outbound reply. The signature is pulled from your Freshservice agent profile (the same one configured under Profile Settings → Signature in the Freshservice portal).

• Signature data comes from the cached get_current_agent call, so there is zero additional API cost.
• If no signature is configured in your profile, replies are sent without one.
• Internal notes (create_ticket_note, add_note_attachment) are not affected — signatures are only appended to replies visible to the requester.

Prompt Examples

Once connected, you can ask things like:

Prompt	What happens	API calls
"Show me my open tickets"	get_my_tickets — looks up your agent ID, discovers all non-resolved statuses, and filters in one shot	1 (warm cache)
"What's ticket #4521 about?"	get_ticket_by_id	1
"Create a ticket for the printer on floor 3"	create_ticket with subject/description/priority	1
"Add a note to ticket #4521 saying we ordered parts"	create_ticket_note	1
"Reply to ticket #4521 letting them know it's fixed"	send_ticket_reply — auto-appends your agent signature	1
"Find that Q4 report"	find_file — searches configured directories for matching files	0
"Attach this screenshot to ticket #4521"	add_ticket_attachment with the file path	1
"Show all changes awaiting approval"	filter_changes with query status:3	1
"What ticket statuses do we have?"	get_ticket_statuses — returns every status categorized as resolved/unresolved	0 (cached)
"Who am I in Freshservice?"	get_current_agent — returns your agent profile	0 (cached)
"What's my access level?"	server_status — shows mode, tool counts, rate limit	0
"The admin added new statuses, refresh the cache"	clear_cache — drops all cached data	0

API Efficiency

Freshservice enforces a per-hour tenant-wide API rate limit. This server is designed to stay well within it:

• 1 tool call = 1 API call for most tools. The server makes zero background calls, zero polling, and zero prefetching — every API call is triggered only when the LLM explicitly invokes a tool. Attachment uploads use multipart form-data and count as a single API call each.
• Compound convenience tools: get_my_tickets chains agent lookup + status discovery + filter into a single tool call (1 API call on warm cache, up to 3 on first use). get_ticket_statuses parses cached field data at zero API cost.
• Rate-limit handling: A custom transport reads X-RateLimit-Remaining on every response and automatically retries on HTTP 429 with the Retry-After delay (up to 3 retries).
• Response caching: Schema and reference-data tools cache successful responses for the duration set by FRESHSERVICE_CACHE_TTL (default 1 hour). These are admin-configured structures that effectively never change mid-session. Repeated lookups cost zero API calls. Use the clear_cache tool to force a refresh.
• Pagination controls: All list endpoints expose page and per_page parameters so the LLM fetches only what it needs. Auto-paginating tools (list_service_items, filter_agents) default to 3 pages max.

Always-On Tools

The server_status and clear_cache tools are always available regardless of mode.

• server_status — Reports the current mode, tool counts, capabilities, cache TTL, and API rate-limit remaining.
• clear_cache — Drops all cached responses so the next call fetches fresh data from the API.

Security Notes

• API key is only sent to your Freshservice domain via Basic auth over HTTPS
• No telemetry, no external calls, no logging of credentials
• Credentials are validated at startup; the server fails fast if FRESHSERVICE_DOMAIN or FRESHSERVICE_APIKEY are missing
• Mode restriction is enforced at tool registration time. Blocked tools don't exist in the MCP server's tool list, so the LLM cannot call them.

Troubleshooting

Symptom	Cause	Fix
RuntimeError: FRESHSERVICE_DOMAIN environment variable is required	Missing or empty FRESHSERVICE_DOMAIN	Make sure the env block in your MCP config has the correct variable name and value
RuntimeError: FRESHSERVICE_APIKEY environment variable is required	Missing or empty FRESHSERVICE_APIKEY	Same — check the env block, or your .env file if running from source
Server starts but tools return 401 Unauthorized	Invalid API key	Regenerate your key in Freshservice Profile Settings and update your config
Server starts but tools return 404 Not Found	Wrong domain format	Use the full domain (yourcompany.freshservice.com), not just the subdomain name
Tools you expect are missing	Mode is too restrictive	Check server_status to see the current mode, then set FRESHSERVICE_MODE to a higher level
No module named node804_freshservice_mcp	Package not installed	Use the uvx config (installs automatically), or run pip install node804-freshservice-mcp
Claude Desktop shows the server as failed / spawn uvx ENOENT	Claude Desktop can't find uvx or python on its PATH	Use the full path to the executable in command (see Claude Desktop)
Stale data after admin changes	Cached response	Ask the LLM to call clear_cache, or set FRESHSERVICE_CACHE_TTL=0 to disable caching

Development

uv sync                # creates .venv from pyproject.toml + uv.lock
uv run pytest tests/

Or with pip: pip install -e ".[dev]" then pytest tests/.

uv.lock pins the full dependency graph with hashes for reproducible installs. After changing dependencies in pyproject.toml, run uv lock and commit the updated lockfile.

Acknowledgements

This project started as a fork of effytech/freshservice_mcp, a single-file proof of concept that wired Freshservice endpoints to MCP. It has since been restructured and largely rewritten, but the original authors' copyright is retained in LICENSE.

AI-Assisted Development

Portions of this project including code, tests, and documentation were developed with the assistance of generative AI (Anthropic's Claude, Chat GPT). All changes are human-reviewed before merge and exercised by the automated test suite, but as with any software, review the code and test against a non-production Freshservice instance before trusting it with write access (standard mode or above) to a live tenant.

License

MIT