freshservice_mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Model Context Protocol (MCP) server for Freshservice, enabling AI models to interact with Freshservice's IT Service Management platform. The server exposes Freshservice API operations as MCP tools that can be called by Claude or other AI assistants.

Development Commands

Setup

# Install uv if not already installed
pip install uv

# Install dependencies
uv sync

# Activate virtual environment (if needed)
source .venv/bin/activate

Running the Server

# Run the server manually (requires API credentials)
uvx freshservice-mcp --env FRESHSERVICE_APIKEY=<your_key> --env FRESHSERVICE_DOMAIN=<your_domain>

# Or run via Python module
python -m freshservice_mcp.server

Testing

# Run a specific test function (tests use asyncio)
python tests/test-fs-mcp.py

# The test file contains individual async test functions that can be enabled by uncommenting them
# at the bottom of the file in the __main__ block

Architecture

Core Components

src/freshservice_mcp/server.py - Single monolithic file containing all MCP tool implementations (~97 functions, ~3000+ lines)

The architecture is straightforward:

• All tool implementations are defined as @mcp.tool() decorated async functions
• Each tool makes HTTP requests to Freshservice API endpoints using httpx.AsyncClient
• Authentication uses HTTP Basic Auth with API key (encoded in get_auth_headers())
• All tools are registered with the FastMCP instance (mcp = FastMCP("freshservice_mcp"))
• Server entry point is main() which calls mcp.run(transport='stdio')

Key Architectural Patterns

1. Enum-based Constants: Status codes, priorities, and other Freshservice constants are defined as IntEnum/Enum classes at the top of server.py (TicketSource, TicketStatus, TicketPriority, ChangeStatus, etc.)