Freshdesk MCP Server (FastMCP Cloud)

A FastMCP-compliant Model Context Protocol (MCP) server for Freshdesk, optimized for deployment on fastmcp.cloud.

Features

• FastMCP 2.0 Compliant: Built with FastMCP 2.0 framework
• Cloud Ready: Optimized for fastmcp.cloud deployment
• 5 Core Tools: Focused set of essential Freshdesk operations
• Header-Based Auth: Secure credential management via HTTP headers

Tools

This server provides the following 5 tools:

1. lookup_contact - Find a contact by email or phone number
2. create_contact - Create a new contact in Freshdesk
3. get_tickets_by_contact - Get all tickets for a contact
4. create_ticket - Create a new support ticket
5. update_ticket - Update an existing ticket

Authentication

Credentials are provided via HTTP headers:

• X-Freshdesk-API-Key or Freshdesk-API-Key: Your Freshdesk API key
• X-Freshdesk-Domain or Freshdesk-Domain: Your Freshdesk domain (e.g., yourcompany.freshdesk.com)

Alternatively, you can set environment variables:

• FRESHDESK_API_KEY
• FRESHDESK_DOMAIN

Deployment to FastMCP Cloud

1. Push to GitHub: Push this repository to a GitHub repository

2. Sign in to FastMCP Cloud: Visit fastmcp.cloud and sign in with your GitHub account

3. Create Project:

   • Click "Create New Project"
   • Select your repository
   • Set the entrypoint to: src/freshdesk_mcp/server.py:mcp

4. Deploy: FastMCP Cloud will automatically build and deploy your server

Your server will be available at: https://your-project.fastmcp.app/mcp

Local Development

Installation

pip install -r requirements.txt

Running Locally

# HTTP transport (default)
python -m freshdesk_mcp.server

# Or using the script
freshdesk-mcp

Environment Variables

For local development, you can set environment variables:

export FRESHDESK_API_KEY="your-api-key"
export FRESHDESK_DOMAIN="yourcompany.freshdesk.com"

Usage Example

Python Client

from fastmcp.client.transports import StreamableHttpTransport
from fastmcp import Client

transport = StreamableHttpTransport(
    url="https://your-project.fastmcp.app/mcp",
    headers={
        "X-Freshdesk-API-Key": "your-api-key",
        "X-Freshdesk-Domain": "yourcompany.freshdesk.com"
    }
)

async with Client(transport) as client:
    # Lookup a contact
    contact = await client.call_tool("lookup_contact", {"email": "user@example.com"})
    print(contact)
    
    # Create a ticket
    ticket = await client.call_tool("create_ticket", {
        "subject": "Support Request",
        "description": "I need help with...",
        "source": 1,  # Email
        "priority": 2,  # Medium
        "status": 2,  # Open
        "email": "user@example.com"
    })
    print(ticket)

cURL Example

curl -X POST https://your-project.fastmcp.app/mcp \
  -H "X-Freshdesk-API-Key: your-api-key" \
  -H "X-Freshdesk-Domain: yourcompany.freshdesk.com" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "lookup_contact",
      "arguments": {
        "email": "user@example.com"
      }
    },
    "id": 1
  }'

Health Check

The server provides a health check endpoint:

curl https://your-project.fastmcp.app/health

Response:

{
  "status": "healthy",
  "service": "freshdesk-mcp",
  "version": "1.0.0"
}

Ticket Source Values

• 1 - Email
• 2 - Portal
• 3 - Phone
• 7 - Chat
• 9 - Feedback Widget
• 10 - Outbound Email

Ticket Priority Values

• 1 - Low
• 2 - Medium
• 3 - High
• 4 - Urgent

Ticket Status Values

• 2 - Open
• 3 - Pending
• 4 - Resolved
• 5 - Closed

Project Structure

FASTMCP-Freshdesk/
├── src/
│   └── freshdesk_mcp/
│       ├── __init__.py
│       └── server.py          # Main server file
├── pyproject.toml              # Project configuration
├── requirements.txt            # Python dependencies
└── README.md                   # This file

License

[Your License Here]

Support

For issues and questions, please open an issue in the repository.