🚀 Don't want to self-host? Join the waitlist for our fully managed solution →

Zero setup. Zero maintenance. Just connect and automate.

---

🎫 Freshdesk MCP Server — AI-Native Support Operations

💡 What This Unlocks

Turn Claude into your L1 support engineer. This MCP server gives AI direct access to your Freshdesk helpdesk—triaging tickets, drafting responses, managing contacts, and surfacing insights—all through natural language commands.

🎯 Freshdesk-Native Power Moves

Real support workflows you can automate instantly:

1. Morning ticket triage ritual
   "Show me all new tickets from the past 12 hours, categorize by urgency, assign high-priority ones to our senior agents, and draft acknowledgment replies for the rest."
   → Automate the first hour of your support day.

2. Customer sentiment analysis
   "Search all tickets from customer email 'john@acme.com', analyze tone across conversations, flag any escalating frustration, suggest proactive outreach strategies."
   → Turn ticket history into relationship intelligence.

3. SLA compliance sweep
   "List all tickets approaching SLA breach (< 2 hours remaining), group by priority, draft urgent response templates, notify assigned agents via their email."
   → Prevent SLA violations before they happen.

4. Knowledge base gap detection
   "Search tickets for recurring phrases like 'how do I', 'can't figure out', 'doesn't work'—identify top 10 repeat questions, draft KB articles for each, assign to documentation team."
   → Data-driven knowledge base strategy.

5. Bulk ticket cleanup operations
   "Find all 'Waiting on Customer' tickets older than 14 days with no response, send polite check-in messages, update status to 'Pending', tag for closure in 7 days if still no reply."
   → Automated ticket hygiene without manual busywork.

🔗 The Real Power: Combining Tools

Claude orchestrates multi-step support workflows:

• search_tickets (keyword/tag) → get_ticket (details) → reply_ticket (drafted response)
• list_tickets (filtered by status) → update_ticket (bulk status changes)
• list_contacts → enrich with ticket history → identify VIP customers
• create_ticket → assign to agent → add private note with context

📦 What's Inside

8 REST API tools covering core Freshdesk support operations:

Tool	Purpose
list_tickets	Query tickets with filters (status, priority, agent, date)
get_ticket	Full ticket details including conversations & metadata
create_ticket	Generate new tickets from any source with custom fields
update_ticket	Modify ticket properties (status, priority, assignment, tags)
reply_ticket	Add public replies or private notes to tickets
list_contacts	Browse contact/requester directory with search
list_agents	View agent roster with availability & roles
search_tickets	Advanced search with Freshdesk query language

All with proper Basic Auth handling, error management, and TypeScript types.

🚀 Quick Start

Option 1: Claude Desktop (Local)

1. Clone and build:

   git clone https://github.com/BusyBee3333/Freshdesk-MCP-2026-Complete.git
   cd freshdesk-mcp-2026-complete
   npm install
   npm run build
   

2. Get your Freshdesk API credentials:

   • Log in to your Freshdesk account
   • Go to Profile Settings → View API Key (right sidebar)
   • Copy your API key (long alphanumeric string)
   • Note your Freshdesk domain (e.g., yourcompany from yourcompany.freshdesk.com)

3. Configure Claude Desktop:

   On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   On Windows: %APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "freshdesk": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/TO/freshdesk-mcp-2026-complete/dist/index.js"],
         "env": {
           "FRESHDESK_API_KEY": "your_api_key_here",
           "FRESHDESK_DOMAIN": "yourcompany"
         }
       }
     }
   }
   

4. Restart Claude Desktop
   You'll see the 🔌 icon with Freshdesk tools available.

Option 2: Docker

docker build -t freshdesk-mcp .
docker run \
  -e FRESHDESK_API_KEY=your_key_here \
  -e FRESHDESK_DOMAIN=yourcompany \
  freshdesk-mcp

🔐 Authentication

Freshdesk uses API Key authentication (HTTP Basic Auth):

1. Find your API key: Profile Settings → View API Key (or regenerate if needed)
2. API Key format: Long alphanumeric string (treat like a password)
3. Authentication method: Basic Auth with API key as username, "X" as password (handled automatically by MCP server)

Security notes:

• API keys have same permissions as your user account (admin keys = full access)
• Never commit API keys to version control
• Rotate keys regularly from Freshdesk settings
• Use environment variables or secrets management for production

Rate limits: Freshdesk enforces rate limits based on plan:

• Estate/Forest plans: 50,000 API calls/hour
• Garden plans: 1,000 API calls/hour
• Sprout/Blossom plans: Varies by plan

🎯 Example Prompts

Once connected to Claude, use natural language for support operations:

Ticket Management

• "Show me all new tickets from the past 24 hours, sorted by priority."
• "Create a ticket from customer john@acme.com: subject 'Login issues', description 'User can't access dashboard', priority High, assign to the Mobile team."
• "Update ticket #12345 to status Resolved, add tag 'billing-issue', and assign to the Billing group."

Ticket Responses

• "Reply to ticket #789 with: 'Thanks for reaching out! I've escalated this to our engineering team. You'll hear back within 24 hours.' Mark as Pending."
• "Add a private note to ticket #456: 'Customer is VIP account—prioritize and offer phone support if needed.'"

Searching & Analysis

• "Search for all tickets with tag 'bug' that are still open, created in the past 7 days."
• "Find tickets containing 'refund request' in the description, show me the top 5 by creation date."
• "Search for tickets assigned to agent sarah@company.com with status 'Waiting on Customer' for more than 5 days."

Contact & Agent Management

• "List all contacts whose email contains '@enterprise.com' and show their ticket history."
• "Show me all active agents, their email addresses, and current ticket workload."

Bulk Operations

• "Find all tickets tagged 'needs-followup' that are older than 3 days, send a check-in message to each customer asking if issue is resolved."
• "List all tickets with priority 4 (Urgent) that don't have an assigned agent—distribute evenly across available agents."

Intelligence Extraction

• "Analyze all resolved tickets from the past month, extract common issues, rank by frequency, generate a report."
• "Which agent has the fastest average response time this week? Show stats for top 5 agents."
• "Identify tickets that have been reopened multiple times—flag for process improvement review."

🛠️ Development

Prerequisites

• Node.js 18+
• npm or yarn
• Freshdesk account with API access enabled

Local Setup

git clone https://github.com/BusyBee3333/Freshdesk-MCP-2026-Complete.git
cd freshdesk-mcp-2026-complete
npm install
cp .env.example .env
# Edit .env with your Freshdesk credentials
npm run build
npm run dev

Testing

npm test                  # Run all tests
npm run test:watch        # Watch mode
npm run test:coverage     # Coverage report

Testing with Freshdesk Sandbox

Freshdesk offers a sandbox environment for testing:

• Clone your production helpdesk to sandbox in admin settings
• Use sandbox domain (yourcompany-sandbox.freshdesk.com)
• Test MCP operations without affecting live tickets

🐛 Troubleshooting

"Authentication failed" / 401 error

• API key incorrect: Double-check you copied the full key from Profile Settings
• Domain mismatch: Ensure FRESHDESK_DOMAIN matches your actual subdomain (without .freshdesk.com)
• Key revoked: If you regenerated your API key, update the environment variable
• Insufficient permissions: Some operations require admin/agent roles

"Tools not appearing in Claude"

• Restart required: Always restart Claude Desktop after config changes
• Absolute paths: Use full paths in config (no ~ or relative paths)
• Build check: Verify dist/index.js exists after running npm run build

"Rate limit exceeded" / 429 error

• Check your plan: Freshdesk limits API calls based on subscription tier
• Throttle requests: Add delays between bulk operations
• Monitor usage: Check API call consumption in Freshdesk admin settings

Ticket operation errors

• Invalid IDs: Freshdesk uses numeric ticket IDs (not strings)
• Status codes: Use numeric status values (2=Open, 3=Pending, 4=Resolved, 5=Closed)
• Custom fields: Check your helpdesk's custom field configuration for valid field names
• Email validation: Requester email must be valid format for ticket creation

📖 Resources

• Freshdesk API v2 Docs — Official REST API reference
• API Authentication Guide — How to use API keys
• Tickets API — Create, update, search tickets
• Contacts API — Manage requesters
• Search Syntax — Advanced search query language
• Webhooks — Real-time event notifications
• MCP Protocol Specification — How MCP servers work
• Claude Desktop Documentation — Desktop app setup

🤝 Contributing

Contributions welcome! To add features:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/ticket-merge)
3. Commit your changes (git commit -m 'Add ticket merge capability')
4. Push to the branch (git push origin feature/ticket-merge)
5. Open a Pull Request

Ideas for contributions:

• Support for ticket attachments (file uploads)
• Custom field management helpers
• Group & company management tools
• Time tracking integration
• Satisfaction survey response parsing
• Canned response library integration
• Ticket merge/split operations
• SLA policy management

📄 License

MIT License - see LICENSE for details

🙏 Credits

Built by MCPEngage — AI infrastructure for business software.

Want more MCP servers? Check out our full catalog covering 30+ business platforms.

---

Questions? Open an issue or join our Discord community.