# Freshdesk MCP Server

A comprehensive Model Context Protocol (MCP) server for Freshdesk, providing AI assistants with complete access to customer support helpdesk operations. This server delivers 98 tools covering ticket management, agent operations, knowledge base, and customer engagement workflows.

## Features

- **Ticket Management**: Create, update, search, and resolve tickets with full SLA tracking and priority management
- **Contact & Company Management**: Comprehensive CRUD operations for contacts and companies with custom field support
- **Agent Operations**: Manage agents, roles, skills, and team assignments
- **Canned Responses**: Access and use pre-written response templates for faster ticket resolution
- **Knowledge Base**: Manage solutions, articles, categories, and forums for self-service support
- **Groups & Roles**: Organize agents into groups with role-based permissions
- **Products**: Track product-specific issues and categorize tickets by product
- **Survey Management**: Create and send customer satisfaction surveys
- **Reporting**: Generate ticket analytics, agent performance reports, and SLA compliance metrics
- **Automation**: Leverage Freshdesk's automation rules through API-driven ticket updates
- **Multi-Channel Support**: Handle tickets from email, chat, phone, and social media
- **Custom Fields**: Extensive custom field support for tickets, contacts, and companies

## Installation

```bash
npm install && npm run build
```

## Environment Variables

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `FRESHDESK_API_KEY` | Yes | Your Freshdesk API key | `aBcDeFgHiJkLmNoPqRs` |
| `FRESHDESK_DOMAIN` | Yes | Your Freshdesk subdomain (without .freshdesk.com) | `yourcompany` |

## Getting Your Access Token

1. **Log in to Freshdesk**: Go to `https://yourcompany.freshdesk.com`
2. **Navigate to Profile Settings**:
   - Click your profile picture in the top right
   - Select **Profile settings**
3. **Locate API Key**:
   - Look for the **Your API Key** section in the right sidebar
   - Your API key will be displayed (it may be hidden behind asterisks)
   - Click **Show** or **View full key** to reveal it
4. **Copy Your API Key**: Copy the full key (typically 20-21 characters)
5. **Set Environment Variables**:
   ```bash
   export FRESHDESK_API_KEY="aBcDeFgHiJkLmNoPqRs"
   export FRESHDESK_DOMAIN="yourcompany"
   ```

**Alternative Method** (Admin):
- Go to **Admin** → **API** section
- Your API key is displayed at the top
- You can also regenerate it if needed (this will invalidate the old key)

**Security Note**: Each agent has their own API key with permissions matching their role. Use service/bot accounts for integrations. Never commit API keys to version control.

## Required API Scopes

Freshdesk API keys inherit the permissions of the user account:

**Full Access** (Admin/Account Admin):
- **Tickets**: Read, create, update, delete, merge tickets
- **Contacts**: Read, create, update, delete contacts
- **Companies**: Read, create, update, delete companies
- **Agents**: Read, create, update, delete agents (admin only)
- **Roles**: Read role information
- **Groups**: Read, create, update, delete groups
- **Products**: Read, create, update, delete products
- **Solutions**: Read, create, update, delete KB articles
- **Forums**: Read, create, update, delete forum topics
- **Canned Responses**: Read and use canned responses
- **Surveys**: Read and send surveys
- **Reports**: Access reporting data

**Agent Access**:
- Limited to tickets they have access to based on group membership
- Can read contacts and companies
- Cannot manage other agents or admin settings

**Requester Access** (not recommended for MCP):
- Can only view their own tickets

## Usage

### stdio Mode (Default)

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "freshdesk": {
      "command": "node",
      "args": [
        "/path/to/mcpengine-repo/servers/freshdesk/dist/index.js"
      ],
      "env": {
        "FRESHDESK_API_KEY": "your_api_key_here",
        "FRESHDESK_DOMAIN": "yourcompany"
      }
    }
  }
}
```

### HTTP Mode

The server can also run as an HTTP endpoint:

```bash
export FRESHDESK_API_KEY="your_api_key_here"
export FRESHDESK_DOMAIN="yourcompany"
npm start -- --http --port 3000
```

Then configure your MCP client to connect to `http://localhost:3000`.

## Coverage Manifest

```
Total API endpoints: ~140 (Freshdesk API v2)
Tools implemented: 98
Intentionally skipped: ~25 (time tracking, business hours, SLA policies, email configs)
Not yet covered: ~17 (ticket fields admin, automations, workflows, satisfaction ratings)
Coverage: 98/140 = 70%
```

**Coverage Notes**:
- ✅ **Complete**: Tickets (15 tools), Contacts (10 tools), Companies (8 tools), Agents (9 tools), Groups (6 tools), Products (6 tools), Canned Responses (6 tools), Solutions/KB (14 tools), Forums (10 tools), Roles (6 tools), Surveys (4 tools), Reporting (4 tools)
- ⏭️ **Skipped**: Time tracking (separate billing addon), business hours configuration, SLA policy management, email server configs, SSO settings
- 🚧 **Planned**: Custom ticket field administration, automation rule management, workflow triggers, CSAT rating retrieval, email template management

## Example Use Cases

- "Create a new support ticket from john@example.com about billing issue"
- "Update ticket #1234 status to 'Pending' and add internal note"
- "Search for all open tickets assigned to Sarah with high priority"
- "Get customer contact details for support@company.com"
- "Create a new solution article in the Getting Started category"
- "List all canned responses in the Billing Responses folder"
- "Add a new contact for Jane Smith at Acme Corp"
- "Merge ticket #5678 into ticket #1234"
- "Get all tickets created in the last 24 hours"
- "Assign ticket #9999 to the Sales Support group"

## Architecture

The server uses Freshdesk API v2 with Basic Authentication:
- **Client**: `FreshDeskClient` with Basic Auth (`apiKey:X` base64-encoded)
- **Tools**: 12 tool modules with 98 total tools
- **Auth**: HTTP Basic Authentication (API key with 'X' as password)
- **Pagination**: Automatic page-based pagination (30 records per page default)
- **Rate Limits**: Respects Freshdesk rate limits (varies by plan, typically 1000-5000 req/hr)
- **Domain**: All requests to `https://{domain}.freshdesk.com/api/v2`

## Links

- [Freshdesk API Documentation](https://developers.freshdesk.com/api/)
- [API v2 Reference](https://developer.freshdesk.com/api/v2/)
- [Authentication Guide](https://developer.freshdesk.com/api/#authentication)
- [Rate Limits](https://developer.freshdesk.com/api/#ratelimit)
- [Error Codes](https://developer.freshdesk.com/api/#http-response-codes)
- [Freshdesk Support](https://support.freshdesk.com/)