Michael Pope
Open Source Freshservice MCP Server

The Node804 Freshservice MCP Server is an open-source Model Context Protocol server that connects AI assistants to the Freshservice REST API in a controlled, auditable way. It is designed for real IT service management workflows where an assistant needs to inspect tickets, search service data, create updates, manage changes, or attach files without exposing every possible API action by default.

Freshservice API access is powerful, but its API key model is broad. This project addresses that risk by putting permission boundaries inside the MCP server itself, so the assistant only sees the tools allowed by the configured operating mode.

Why I Built It

AI assistants are most useful in IT operations when they can work with the systems where tickets, changes, approvals, requesters, assets, and knowledge live. But exposing a full ITSM API to an LLM without guardrails is not responsible engineering.

This server was built around a practical goal: make Freshservice useful to AI workflows while preserving operational control.

The result is an MCP server that is:

  • Open source under the MIT license
  • Permission-gated through explicit operating modes
  • Useful by default in read-only mode
  • Structured for real ITSM workflows, not API demos
  • Designed for local or controlled deployment, with no telemetry or credential logging

Open Source Design

This project is published openly so other IT teams, automation engineers, and MCP builders can inspect it, run it, adapt it, and improve it. The repository includes the package source, tests, documentation, CI workflow, PyPI packaging, and setup examples for Claude Desktop and Claude Code.

That matters because MCP servers sit between an AI assistant and operational systems. The implementation should be reviewable. Users should be able to see which tools exist, how permission modes are enforced, how API calls are made, and where credentials are handled.

Open sourcing the server also makes it easier for others to extend support for Freshservice workflows without starting from scratch.

Permission-Based Tool Gating

The main safety feature is FRESHSERVICE_MODE, which controls which tools are registered with the MCP server:

  • read: view, search, list, and filter across Freshservice modules with no modifications
  • standard: day-to-day ticket/change work such as creating tickets, adding notes, replying, handling approvals, and service requests
  • full: content and requester administration, including solution article and requester management
  • admin: full administrative access, including destructive operations

Blocked tools are not merely hidden in documentation. They are excluded at registration time, meaning the LLM cannot call them because they do not exist in the exposed tool list.

That model is important because Freshservice provides a single API key per account with no native scoping. The MCP layer becomes the practical safety boundary.

What It Can Do

The server covers the core Freshservice surfaces I wanted an assistant to work with:

  • Tickets, replies, notes, attachments, and time entries
  • Changes, approvals, notes, tasks, and time entries
  • Service catalog items and requests
  • Products and requesters
  • Agents and groups
  • Canned responses, workspaces, and solution articles
  • Local file search for attachment discovery

It also includes always-on operational tools such as server_status and clear_cache, so a user can confirm the active mode, tool count, cache behavior, and API rate-limit state before asking the assistant to take action.

Engineering Highlights

Several design choices make the server more than a thin API wrapper:

  • Rate-limit handling reads Freshservice rate-limit headers and retries on 429 responses.
  • Configurable caching keeps schema and reference-data lookups efficient.
  • Pagination controls prevent broad list operations from pulling more data than needed.
  • Credential validation fails fast when required environment variables are missing.
  • Attachment workflows support finding local files before uploading them to tickets.
  • Tests and CI cover configuration, permission mapping, caching, rate limiting, convenience tools, and attachments.

The project is also packaged for simple use through uvx or pip, making it usable without cloning the repository.

Practical Impact

For a service desk or infrastructure team, this server turns an AI assistant into a safer operational helper. It can answer questions like:

  • “Show me my open tickets.”
  • “What’s ticket #4521 about?”
  • “Create a ticket for the printer on floor 3.”
  • “Add an internal note to this ticket.”
  • “Show all changes awaiting approval.”
  • “Find the Q4 report so I can attach it.”

The key is that each of those actions can be limited by mode. A read-only assistant can inspect. A standard-mode assistant can help with daily work. Administrative actions require an explicit configuration decision.