Freshservice MCP Server

A Model Context Protocol (MCP) server that connects Claude, Codex, and other MCP clients to your Freshservice ITSM instance.

Supported modules

Prerequisites

• Python 3.10+
• uv — fast Python package manager
• Claude Desktop, Claude Code, or Codex app/CLI/IDE (see Setup below)
• A Freshservice account with an API key

Install uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with Homebrew
brew install uv

Get your Freshservice API key

1. Log in to your Freshservice portal
2. Click your profile picture → Profile Settings
3. Your API key is shown on the right side under Change Password

Setup

1. Clone the repository

git clone https://github.com/matthewlboyd/freshservice-mcp.git
cd freshservice-mcp

2a. Configure Claude Desktop

Option A — macOS install script (recommended):

./install.sh

This handles everything automatically: prompts for your repo path, API key, and domain, writes the config, tests the connection, and restarts Claude Desktop.

Option B — Manual setup (all platforms):

Open the Claude Desktop config file in any text editor:

Paste the following into the file, replacing the placeholder values. If the file doesn't exist yet, create it with just this content:

{
  "mcpServers": {
    "freshservice": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/full/path/to/freshservice-mcp",
        "freshservice-mcp"
      ],
      "env": {
        "FRESHSERVICE_APIKEY": "your_api_key_here",
        "FRESHSERVICE_DOMAIN": "yourcompany.freshservice.com"
      }
    }
  }
}

FRESHSERVICE_DOMAIN should be just the hostname — no https:// prefix.

If you're behind a corporate proxy with SSL inspection, add SSL_CERT_FILE to the env block pointing at your CA bundle:

"env": {
  "FRESHSERVICE_APIKEY": "your_api_key_here",
  "FRESHSERVICE_DOMAIN": "yourcompany.freshservice.com",
  "SSL_CERT_FILE": "/path/to/your/ca-bundle.crt"
}

Already have other MCP servers? Add just the "freshservice": { ... } block inside your existing "mcpServers" object instead of replacing the whole file.

Restart Claude Desktop — quit and reopen it. The first launch will automatically install dependencies (takes ~30 seconds). You should see a hammer icon (🔨) in the chat input, indicating MCP tools are available.

2b. Configure Claude Code

Recommended: project-local scope

claude mcp add freshservice \
  --scope local \
  --env FRESHSERVICE_APIKEY=your_api_key_here \
  --env FRESHSERVICE_DOMAIN=yourcompany.freshservice.com \
  -- uv run --directory /full/path/to/freshservice-mcp freshservice-mcp

--scope local stores the config in .claude/settings.local.json, which is gitignored by default — your API key will not be committed to version control.

Alternative: user scope (available in all your projects)

claude mcp add freshservice \
  --scope user \
  --env FRESHSERVICE_APIKEY=your_api_key_here \
  --env FRESHSERVICE_DOMAIN=yourcompany.freshservice.com \
  -- uv run --directory /full/path/to/freshservice-mcp freshservice-mcp

Security note: Never use --scope project with credentials hardcoded in the command — the project scope writes to .mcp.json, which is typically committed to version control. Use local or user scope, or pass credentials via environment variables already set in your shell.

If you're behind a corporate proxy with SSL inspection, add --env SSL_CERT_FILE=/path/to/your/ca-bundle.crt to the command above.

Verify the server is registered:

claude mcp list

You should see freshservice in the output. No restart is needed — Claude Code picks up MCP servers at the start of each session.

2c. Configure Codex app, CLI, or IDE

Codex app, Codex CLI, and the Codex IDE extension share MCP configuration through config.toml. The server uses Codex-supported stdio transport and can run through the Codex-specific entrypoint alias freshservice-mcp-codex.

Option A — install script:

./install-codex.sh

This prompts for your repo path, Freshservice API key, domain, and optional CA bundle, then writes a [mcp_servers.freshservice] block to ~/.codex/config.toml (or $CODEX_HOME/config.toml if CODEX_HOME is set).

Option B — Codex CLI:

codex mcp add freshservice \
  --env FRESHSERVICE_APIKEY=your_api_key_here \
  --env FRESHSERVICE_DOMAIN=yourcompany.freshservice.com \
  -- uv run --directory /full/path/to/freshservice-mcp freshservice-mcp-codex

If you're behind a corporate proxy with SSL inspection, add --env SSL_CERT_FILE=/path/to/ca-bundle.crt.

Option C — manual `config.toml`:

Open Codex Settings → Integrations & MCP → Open config.toml, or edit ~/.codex/config.toml directly. Add this block, replacing the placeholders:

[mcp_servers.freshservice]
enabled = true
command = "uv"
args = [
  "run",
  "--directory",
  "/full/path/to/freshservice-mcp",
  "freshservice-mcp-codex",
]
startup_timeout_sec = 30
tool_timeout_sec = 120

[mcp_servers.freshservice.env]
FRESHSERVICE_APIKEY = "your_api_key_here"
FRESHSERVICE_DOMAIN = "yourcompany.freshservice.com"

FRESHSERVICE_DOMAIN should be just the hostname — no https:// prefix.

If you're behind a corporate proxy with SSL inspection, add this to the env block:

SSL_CERT_FILE = "/path/to/your/ca-bundle.crt"

Security note: Values under [mcp_servers.freshservice.env] are stored in plaintext in config.toml. If you already provide these variables to the Codex process another way, you can use env_vars = ["FRESHSERVICE_APIKEY", "FRESHSERVICE_DOMAIN"] instead of the env table.

Restart the Codex app, or start a new Codex CLI/IDE session. In Codex, use /mcp to confirm the freshservice server is loaded.

Example prompts

Tickets

• "Show me all open urgent tickets"
• "Create a ticket for a VPN connectivity issue — assign to the Network team, high priority"
• "Update ticket #4521 to resolved"
• "Find all tickets created this week by [email protected]"

Changes

• "Create a change request for server maintenance this Saturday, 10pm–2am"
• "Show all changes awaiting approval"
• "Close change #89 — migration completed successfully"

Assets

• "List all laptops in the asset inventory"
• "Search for assets tagged 'datacenter'"
• "Show all unassigned hardware assets"

Knowledge Base

• "Search the knowledge base for VPN setup instructions"
• "Create a new solution article on how to reset your password"
• "List all articles in the Onboarding folder"

General

• "How many open tickets are assigned to the Help Desk group?"
• "List all active agents and their departments"
• "Show me all software registered in the system"

Running the tests

The test suite covers all 62 tools and the API client (117 tests total). No Freshservice credentials are needed — all tests use mocked HTTP calls.

Install dev dependencies:

uv pip install -e ".[dev]"

Run all tests:

uv run pytest tests/ -v

Run a specific module's tests:

uv run pytest tests/test_tickets.py -v

Test files:

Troubleshooting

Tools don't appear in Claude Desktop Make sure the path in --directory is the absolute path to the repo and that you've fully quit and restarted Claude (not just closed the window).

Tools don't appear in Claude Code Run claude mcp list to confirm the server is registered. If it is, start a new claude session — MCP servers are loaded at session start. If it's missing, re-run the claude mcp add command.

Tools don't appear in Codex Check ~/.codex/config.toml (or $CODEX_HOME/config.toml) for the [mcp_servers.freshservice] block, then restart the Codex app or start a new Codex CLI/IDE session. In Codex, run /mcp to inspect loaded MCP servers. If first launch times out while uv installs dependencies, keep startup_timeout_sec = 30 or increase it.

Authentication error (401) Your API key is incorrect. Double-check it in Freshservice → Profile Settings. Copy it using the copy icon rather than selecting the text manually.

403 Forbidden The API key doesn't have permission for that operation, or the domain is wrong. Confirm FRESHSERVICE_DOMAIN is just the hostname (e.g. yourcompany.freshservice.com), with no https:// prefix.

SSL certificate errors If you're behind a corporate proxy with SSL inspection, requests will fail with a certificate verification error. Set the SSL_CERT_FILE environment variable to the path of your organisation's CA bundle. In Claude Desktop, add it to the "env" block in claude_desktop_config.json. In Claude Code, pass --env SSL_CERT_FILE=/path/to/ca-bundle.crt when running claude mcp add. In Codex, add SSL_CERT_FILE = "/path/to/ca-bundle.crt" under [mcp_servers.freshservice.env].

Rate limiting (429) Freshservice enforces per-minute API rate limits based on your plan. Wait a moment and try again.

Filter queries returning errors Filter strings must use double-quoted field values. Example: "status:2 AND priority:4" not status:2 AND priority:4.

Checking logs If something isn't working, check the MCP server logs:

• macOS: ~/Library/Logs/Claude/mcp-server-freshservice.log
• Windows: %APPDATA%\Claude\logs\mcp-server-freshservice.log

License

MIT