# Freshdesk MCP Server

A Model Context Protocol (MCP) server that exposes Freshdesk helpdesk operations as callable tools. It provides full ticket lifecycle management, two-phase draft/send for replies and notes, contact lookup, and agent/group discovery — all through a standard MCP interface compatible with any MCP client.

## Features

- 14 tools covering tickets, replies, notes, contacts, groups, and agents
- Two-phase draft/send pattern for replies and notes — review before posting
- Custom fields support on ticket create and update
- Predefined filters and full query-syntax search for tickets
- Client-agnostic: works with any MCP-compatible host

## Prerequisites

- Node.js 18 or later
- A Freshdesk account with API access

## Getting Your API Key

1. Log in to your Freshdesk account
2. Click your avatar in the top-right corner and select **Profile Settings**
3. Your API key is displayed in the right sidebar under **Your API Key**

## Installation

```bash
git clone https://github.com/ArcaneSK/freshdesk-mcp-server.git
cd freshdesk-mcp-server
npm install
npm run build
```

### Environment Setup

Copy the example environment file and fill in your credentials:

```bash
cp .env.example .env
```

Edit `.env` with your values:

```
FRESHDESK_API_KEY=your_api_key_here
FRESHDESK_DOMAIN=your_subdomain
```

| Variable | Description | Example |
|----------|-------------|---------|
| `FRESHDESK_API_KEY` | Your Freshdesk API key (see [Getting Your API Key](#getting-your-api-key)) | `abcdef123456` |
| `FRESHDESK_DOMAIN` | Your Freshdesk subdomain — if your URL is `https://acme.freshdesk.com`, use `acme` | `acme` |

### Claude Desktop Configuration

Add the following to your Claude Desktop `claude_desktop_config.json`, replacing the path with your actual install location:

```json
{
  "mcpServers": {
    "freshdesk": {
      "command": "node",
      "args": ["/path/to/freshdesk-mcp-server/dist/index.js"],
      "env": {
        "FRESHDESK_API_KEY": "your_api_key",
        "FRESHDESK_DOMAIN": "your_subdomain"
      }
    }
  }
}
```

Set `FRESHDESK_DOMAIN` to your Freshdesk subdomain only — for example, if your helpdesk URL is `https://acme.freshdesk.com`, use `acme`.

## Tools Reference

| Tool | Description | Key Inputs |
|------|-------------|------------|
| `list_tickets` | List tickets using predefined filters | `filter`, `email`, `requester_id`, `page` |
| `search_tickets` | Search tickets using Freshdesk query syntax | `query` (max 512 chars) |
| `get_ticket` | Retrieve a single ticket with all fields | `ticket_id`, `include` (conversations, requester, stats) |
| `create_ticket` | Create a new ticket | `subject`, `description`, `email` or `requester_id` |
| `update_ticket` | Update ticket fields | `ticket_id`, `status`, `priority`, `responder_id`, `custom_fields` |
| `delete_ticket` | Move a ticket to trash | `ticket_id` |
| `draft_reply` | Stage a reply for review (does not send) | `ticket_id`, `body`, `cc_emails` |
| `send_reply` | Send a previously drafted reply | `draft_id` |
| `draft_note` | Stage a note for review (does not post) | `ticket_id`, `body`, `private` |
| `send_note` | Post a previously drafted note | `draft_id` |
| `list_contacts` | List contacts by email or search term | `email`, `search_term`, `page` |
| `get_contact` | Get full contact details by ID | `contact_id` |
| `list_groups` | List all agent groups | `page`, `per_page` |
| `list_agents` | List agents, optionally filtered by group | `group_id`, `page` |

## Two-Phase Draft/Send

Replies and notes use a two-step confirmation pattern to prevent accidental sends:

1. Call `draft_reply` or `draft_note` with the content. The tool returns a `draft_id` and a preview of the content — nothing is sent to Freshdesk.
2. Review the draft, then call `send_reply` or `send_note` with the `draft_id` to post it.

Drafts are held in memory with a 10-minute expiration window. Each draft can only be sent once. If a draft expires, create a new one.

## Development

```bash
# Clone and install
git clone https://github.com/ArcaneSK/freshdesk-mcp-server.git
cd freshdesk-mcp-server
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode (TypeScript)
npm run dev
```

## License

MIT