Freshdesk Server

Hey! This is a custom Model Context Protocol (MCP) server for Freshdesk. It's built on top of FastMCP to let your AI agents (like Claude Desktop or custom LangChain setups) read and write directly to your Freshdesk account.

What can it do?

I've packed in a bunch of tools so the AI can handle almost any helpdesk task:

Tickets & Responses

• get_tickets: Search and filter incoming tickets.
• get_ticket: Pull all details for a specific ticket.
• create_ticket: Open a new support ticket.
• update_ticket: Change status or priority.
• delete_ticket: Trash a ticket (be careful with this one).
• reply_ticket: Send a reply to the customer.
• add_note: Drop an internal or public note on a thread.
• list_conversations: Grab the entire back-and-forth history of a ticket.
• create_outbound_email: Send proactive emails (fully supports CC, BCC, tags, and custom fields).

Customers & Companies

• search_contacts: Look up customers by email or phone.
• get_contact / create_contact / update_contact: Manage your user base.
• get_company / create_company: Manage companies.

Agents & Knowledge Base

• list_agents / get_agent: See who is working on what.
• search_solution_articles / get_solution_article: Let the AI search your help docs so it can answer questions better.

How to run it locally

If you just want to run this locally on your own machine (like inside Claude Desktop), it's super simple:

1. Clone this repo and set up your environment:

   python -m venv venv
   source venv/bin/activate
   pip install -e .
   

2. Copy the .env.example file to .env and drop in your Freshdesk domain and API key.
3. Start it up:

   mcp dev src/freshdesk_mcp/server.py
   

Running it on a Network (Secure JWT Auth)

If you're hosting this on a cloud server so multiple remote agents can talk to it, you don't want just anyone hitting your API. I built a lightweight, database-free JWT authentication layer over the SSE connection to keep it safe.

Here's how to use it:

1. In your .env, set up your JWT_SECRET_KEY and define who is allowed to connect using ALLOWED_CLIENTS=agent1:pass123,agent2:secure456.
2. Run the secure server wrapper:

   python -m freshdesk_mcp.serve
   

3. Your clients will first need to send a POST request to /token (using Basic Auth with their agent credentials) to get a 1-hour JWT.
4. They can then connect to the main MCP stream by passing Authorization: Bearer <their_token> in the headers.

(Pro-tip: If you want to make sure an AI agent can only read data and doesn't accidentally delete anything, just set STRICT_MODE=True in your .env and it will lock down all destructive tools).

License

MIT License - feel free to use and modify it however you need!