# Freshdesk MCP 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:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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!