jake/freshdesk-mcp-2026-complete
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rebrand to MCPEngage + deep Freshdesk customization

Browse Source 
- Fix all MCPEngine → MCPEngage references
- Add Freshdesk-specific Power Moves (5 support/helpdesk use cases)
- Correct tool count (8 REST API tools) with accurate descriptions
- Add support-specific prompts (triaging, SLA management, KB gaps)
- Document Freshdesk API key authentication (Basic Auth)
- Link to official Freshdesk API v2 docs
- Update .env.example with FRESHDESK_DOMAIN requirement
- Add rate limiting & status code troubleshooting
This commit is contained in:
Jake Shore 2026-02-02 06:59:48 -05:00
parent b93073b1f5
commit cb341fbdc2
3 changed files with 153 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.env.example
View File

@ -1,2 +1,4 @@
# Freshdesk API Credentials
# Find your API key: Profile Settings → View API Key
FRESHDESK_API_KEY=your-api-key-here
FRESHDESK_DOMAIN=yourcompany

207
README.md
View File

@ -4,34 +4,61 @@
---
# 🚀 Freshdesk MCP Server — 2026 Complete Version
# 🎫 Freshdesk MCP Server — AI-Native Support Operations
## 💡 What This Unlocks
**This MCP server gives AI direct access to your entire Freshdesk workspace.** Instead of clicking through interfaces, you just *tell* it what you need.
**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
The AI can directly control your Freshdesk account with natural language:
Real support workflows you can automate instantly:
- **Smart automation** — Complex workflows in plain English
- **Data intelligence** — Query, analyze, and export your Freshdesk data
- **Rapid operations** — Bulk actions that would take hours manually
- **Cross-platform integration** — Combine Freshdesk with other tools seamlessly
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
AI can chain multiple Freshdesk operations together:
Claude orchestrates multi-step support workflows:
- Query data → Filter results → Generate reports
- Search records → Update fields → Notify team
- Analyze metrics → Create tasks → Schedule follow-ups
- `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
**73 API tools** covering the entire Freshdesk platform (Support & Helpdesk).
**8 REST API tools** covering core Freshdesk support operations:
All with proper error handling, automatic authentication, and TypeScript types.
| 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
@ -45,12 +72,15 @@ All with proper error handling, automatic authentication, and TypeScript types.
npm run build
```
2. **Get your Freshdesk API credentials** (see Authentication section below)
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 macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
@ -58,58 +88,87 @@ All with proper error handling, automatic authentication, and TypeScript types.
"mcpServers": {
"freshdesk": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/freshdesk-mcp/dist/index.js"],
"args": ["/ABSOLUTE/PATH/TO/freshdesk-mcp-2026-complete/dist/index.js"],
"env": {
"FRESHDESK_API_KEY": "your-api-key-here"
"FRESHDESK_API_KEY": "your_api_key_here",
"FRESHDESK_DOMAIN": "yourcompany"
}
}
}
}
```
4. **Restart Claude Desktop**
4. **Restart Claude Desktop**
You'll see the 🔌 icon with Freshdesk tools available.
### Option 2: Deploy to Railway
[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/freshdesk-mcp)
1. Click the button above
2. Set your Freshdesk API credentials in Railway dashboard
3. Use the Railway URL as your MCP server endpoint
### Option 3: Docker
### Option 2: Docker
```bash
docker build -t freshdesk-mcp .
docker run -p 3000:3000 \
-e FRESHDESK_API_KEY=your-key \
docker run \
-e FRESHDESK_API_KEY=your_key_here \
-e FRESHDESK_DOMAIN=yourcompany \
freshdesk-mcp
```
## 🔐 Authentication
See the official [Freshdesk API documentation](https://docs.freshdesk.com) for authentication details.
Freshdesk uses **API Key authentication** (HTTP Basic Auth):
The MCP server handles token refresh automatically.
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, you can use natural language. Examples:
Once connected to Claude, use natural language for support operations:
- *"Show me recent activity in Freshdesk"*
- *"Create a new record with these details..."*
- *"Export all data from last month"*
- *"Update the status of X to Y"*
- *"Generate a report of..."*
### 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
- Freshdesk account with API access enabled
### Setup
### Local Setup
```bash
git clone https://github.com/BusyBee3333/Freshdesk-MCP-2026-Complete.git
@ -118,7 +177,7 @@ npm install
cp .env.example .env
# Edit .env with your Freshdesk credentials
npm run build
npm start
npm run dev
```
### Testing
@ -129,44 +188,78 @@ 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"
- Verify your API credentials are correct
- Check that your API key hasn't been revoked
- Ensure you have the necessary permissions
### "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 Claude Desktop after updating config
- Check that the path in `claude_desktop_config.json` is absolute
- Verify the build completed successfully (`dist/index.js` exists)
- **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 Documentation](https://docs.freshdesk.com)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Desktop Documentation](https://claude.ai/desktop)
- **[Freshdesk API v2 Docs](https://developers.freshdesk.com/api/)** — Official REST API reference
- **[API Authentication Guide](https://developers.freshdesk.com/api/#authentication)** — How to use API keys
- **[Tickets API](https://developers.freshdesk.com/api/#tickets)** — Create, update, search tickets
- **[Contacts API](https://developers.freshdesk.com/api/#contacts)** — Manage requesters
- **[Search Syntax](https://developers.freshdesk.com/api/#filter_tickets)** — Advanced search query language
- **[Webhooks](https://developers.freshdesk.com/api/#webhooks)** — Real-time event notifications
- **[MCP Protocol Specification](https://modelcontextprotocol.io/)** — How MCP servers work
- **[Claude Desktop Documentation](https://claude.ai/desktop)** — Desktop app setup
## 🤝 Contributing
Contributions are welcome! Please:
Contributions welcome! To add features:
1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing-tool`)
3. Commit your changes (`git commit -m 'Add amazing tool'`)
4. Push to the branch (`git push origin feature/amazing-tool`)
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](LICENSE) for details
## 🙏 Credits
Built by [MCPEngine](https://mcpengage.com) — AI infrastructure for business software.
Built by [MCPEngage](https://mcpengage.com) — AI infrastructure for business software.
Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms.
---
**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengine).
**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage).

2
package.json
View File

@ -4,7 +4,7 @@
"description": "MCP server for Freshdesk API - 2026 Complete Version",
"type": "module",
"main": "dist/index.js",
"author": "MCPEngine <hello@mcpengage.com>",
"author": "MCPEngage <hello@mcpengage.com>",
"license": "MIT",
"repository": {
"type": "git",