# Freshservice MCP Server

A fully-featured [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server for [Freshservice](https://freshservice.com) ITSM, deployed on Cloudflare Workers. Exposes **159 tools** covering every Freshservice API v2 endpoint — tickets, assets, changes, problems, releases, projects, service catalog, knowledge base, and more.

## Features

- **159 tools** across 25 modules covering the full Freshservice API v2
- **Cloudflare Workers** — globally distributed, serverless, no cold starts
- **Streamable HTTP** transport (modern MCP standard)
- **Bearer token auth** to protect the MCP endpoint
- **Plan-aware** — each tool description indicates the minimum Freshservice plan required (Starter, Growth, or Pro)

## Setup

### 1. Install dependencies

```bash
npm install
```

### 2. Configure secrets

Copy `.dev.vars.example` to `.dev.vars` for local development:

```bash
cp .dev.vars.example .dev.vars
```

Edit `.dev.vars` with your values:

- **FRESHSERVICE_API_KEY**: Your Freshservice API key (Profile Settings > API Key)
- **FRESHSERVICE_DOMAIN**: Your subdomain (e.g., `yourcompany` for `yourcompany.freshservice.com`)
- **MCP_AUTH_TOKEN**: Bearer token to protect the endpoint. Generate: `openssl rand -hex 32`

### 3. Local development

```bash
npm run dev
```

Server starts at `http://localhost:8787`. Health check at `GET /`, MCP endpoint at `POST /mcp`.

### 4. Deploy

```bash
npx wrangler secret put FRESHSERVICE_API_KEY
npx wrangler secret put FRESHSERVICE_DOMAIN
npx wrangler secret put MCP_AUTH_TOKEN
npm run deploy
```

## Connecting to Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "freshservice": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://freshservice-mcp.<your-account>.workers.dev/mcp",
        "--header",
        "Authorization: Bearer <YOUR_MCP_AUTH_TOKEN>"
      ]
    }
  }
}
```

## Available Tools (159 total)

Each tool description is prefixed with the minimum Freshservice plan required: `[Plan: Starter+]`, `[Plan: Growth+]`, or `[Plan: Pro+]`.

### Starter+ (all plans)

| Module | Tools |
|--------|-------|
| Tickets (15) | `list_tickets`, `get_ticket`, `create_ticket`, `update_ticket`, `delete_ticket`, `list_ticket_conversations`, `add_ticket_note`, `reply_to_ticket`, `list_ticket_time_entries`, `create_ticket_time_entry`, `update_ticket_time_entry`, `delete_ticket_time_entry`, `list_ticket_tasks`, `create_ticket_task`, `list_ticket_approvals` |
| Agents/Requesters (8) | `list_agents`, `get_agent`, `create_agent`, `update_agent`, `delete_agent`, `list_requesters`, `get_requester`, `list_requester_fields` |
| Knowledge Base (13) | `search_articles`, `get_article`, `create_article`, `update_article`, `delete_article`, `list_solution_categories`, `get_solution_category`, `create_solution_category`, `list_solution_folders`, `get_solution_folder`, `create_solution_folder`, `update_solution_folder`, `delete_solution_folder` |
| Departments (5) | `list_departments`, `get_department`, `create_department`, `update_department`, `delete_department` |
| Locations (5) | `list_locations`, `get_location`, `create_location`, `update_location`, `delete_location` |
| Agent Groups (5) | `list_groups`, `get_group`, `create_group`, `update_group`, `delete_group` |
| Requester Groups (5) | `list_requester_groups`, `get_requester_group`, `create_requester_group`, `update_requester_group`, `delete_requester_group` |
| Roles (2) | `list_roles`, `get_role` |
| Announcements (5) | `list_announcements`, `get_announcement`, `create_announcement`, `update_announcement`, `delete_announcement` |
| Canned Responses (5) | `list_canned_responses`, `get_canned_response`, `create_canned_response`, `update_canned_response`, `delete_canned_response` |
| Surveys (5) | `list_surveys`, `get_survey`, `create_survey`, `update_survey`, `delete_survey` |

### Growth+ (Growth, Pro, Enterprise)

| Module | Tools |
|--------|-------|
| Assets (6) | `list_assets`, `get_asset`, `create_asset`, `update_asset`, `delete_asset`, `list_asset_contracts` |
| Asset Types (5) | `list_asset_types`, `get_asset_type`, `create_asset_type`, `update_asset_type`, `delete_asset_type` |
| Service Catalog (4) | `list_service_catalog_items`, `get_service_catalog_item`, `request_service_catalog_item`, `list_service_catalog_categories` |
| Vendors (5) | `list_vendors`, `get_vendor`, `create_vendor`, `update_vendor`, `delete_vendor` |
| Products (5) | `list_products`, `get_product`, `create_product`, `update_product`, `delete_product` |
| Purchase Orders (5) | `list_purchase_orders`, `get_purchase_order`, `create_purchase_order`, `update_purchase_order`, `delete_purchase_order` |
| Business Hours (5) | `list_business_hours`, `get_business_hours_config`, `create_business_hours`, `update_business_hours`, `delete_business_hours` |
| Onboarding (3) | `list_onboarding_requests`, `get_onboarding_request`, `create_onboarding_request` |

### Pro+ (Pro, Enterprise)

| Module | Tools |
|--------|-------|
| Changes (10) | `list_changes`, `get_change`, `create_change`, `update_change`, `delete_change`, `add_change_note`, `list_change_time_entries`, `create_change_time_entry`, `list_change_tasks`, `create_change_task` |
| Problems (10) | `list_problems`, `get_problem`, `create_problem`, `update_problem`, `delete_problem`, `add_problem_note`, `list_problem_time_entries`, `create_problem_time_entry`, `list_problem_tasks`, `create_problem_task` |
| Releases (10) | `list_releases`, `get_release`, `create_release`, `update_release`, `delete_release`, `add_release_note`, `list_release_time_entries`, `create_release_time_entry`, `list_release_tasks`, `create_release_task` |
| Projects (8) | `list_projects`, `get_project`, `create_project`, `update_project`, `delete_project`, `list_project_tasks`, `create_project_task`, `add_project_note` |
| Contracts (5) | `list_contracts`, `get_contract`, `create_contract`, `update_contract`, `delete_contract` |
| Custom Objects (5) | `list_custom_objects`, `get_custom_object`, `create_custom_object`, `update_custom_object`, `delete_custom_object` |

## Tech Stack

- **TypeScript** on **Cloudflare Workers**
- [`agents`](https://npmjs.com/package/agents) (Cloudflare's agents-sdk, includes `@modelcontextprotocol/sdk`)
- [`hono`](https://hono.dev) web framework
- [`zod`](https://zod.dev) schema validation

## Authentication

The MCP endpoint requires a Bearer token in the `Authorization` header. The Freshservice API is accessed using Basic Auth with your API key (stored as a Cloudflare Worker secret).

## License

MIT