# gorgias-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)

MCP server for [Gorgias](https://gorgias.com), the e-commerce customer support helpdesk. 5 tools for AI agents to triage tickets, read full conversation context, draft internal notes for human reviewers, send outbound replies when authorized, and look up customer lifetime history.

As of May 2026, Gorgias does not have an official MCP server. The community attempt is a zero-star placeholder. This is the production-quality rail to fill that gap so external agents (Cursor, Claude Desktop, Hermes, LangChain, n8n) can natively manage Gorgias tickets.

## The 5 tools

| Tool | Purpose |
|---|---|
| `list_open_tickets` | Retrieve unresolved support tickets ordered by most-recent update |
| `get_ticket_context` | Fetch the entire conversation history of a specific ticket |
| `draft_internal_note` | Leave an invisible internal note on a ticket (SAFE path, never visible to customer) |
| `send_ticket_reply` | Send an outward-facing reply to the customer (gated by env-flag) |
| `get_customer_history` | Look up a customer profile by email for lifetime history grounding |

## Install

```bash
pip install gorgias-mcp
```

## Configure

```bash
export GORGIAS_DOMAIN="your-store-subdomain"      # e.g. mystore (NOT mystore.gorgias.com)
export GORGIAS_EMAIL="your-gorgias-user-email"
export GORGIAS_API_KEY="your-gorgias-api-key"
export GORGIAS_ALLOW_OUTBOUND_REPLIES="false"     # set to "true" to enable send_ticket_reply
```

Get a Gorgias API key in your Gorgias dashboard under **Settings -> REST API -> Generate API Key**. The auth model is HTTP Basic where username = the Gorgias user email and password = the API key.

## Use with Claude Desktop

```json
{
  "mcpServers": {
    "gorgias": {
      "command": "gorgias-mcp",
      "env": {
        "GORGIAS_DOMAIN": "your-store-subdomain",
        "GORGIAS_EMAIL": "your-gorgias-user-email",
        "GORGIAS_API_KEY": "your-gorgias-api-key",
        "GORGIAS_ALLOW_OUTBOUND_REPLIES": "false"
      }
    }
  }
}
```

Restart Claude Desktop. The 5 Gorgias tools are now available.

## Use case: AI customer-support assistant

Typical agent flow:

1. Call `list_open_tickets(limit=10)` to find recent unresolved tickets
2. For each ticket, call `get_ticket_context(ticket_id)` to read the full conversation
3. Call `get_customer_history(email_address)` to ground the response in prior interactions
4. Call `draft_internal_note(ticket_id, body_text, sender_id)` to leave AI-generated context for the human support agent who will reply
5. (Optional, only if `GORGIAS_ALLOW_OUTBOUND_REPLIES=true`) Call `send_ticket_reply` to send an autonomous reply

## Safety note

The `draft_internal_note` tool is the recommended primary path for AI-generated content. Internal notes are invisible to customers and let a human reviewer approve before any outbound action. The `send_ticket_reply` tool is GATED behind the `GORGIAS_ALLOW_OUTBOUND_REPLIES` env var (default `false`). Setting it to `true` should be deliberate, in workflows where the AI has been explicitly authorized to message customers without review.

## Architecture

- Public MIT-licensed wrapper around the Gorgias REST API
- Async HTTP via `httpx`
- pydantic v2 input validation
- HTTP Basic Auth (base64-encoded `GORGIAS_EMAIL:GORGIAS_API_KEY`), server-side only
- Outbound-reply gating via env-flag
- Rate-limit aware (429 returns a clean error per Gorgias plan tier)

## Development

```bash
git clone https://github.com/NoBanks/gorgias-mcp.git
cd gorgias-mcp
pip install -e ".[dev]"
pytest
```

## License

MIT. See [LICENSE](LICENSE).

## Author

Ryan Hammer (NoBanks). Solo founder + engineer. Built this and 8 other MCP servers as part of a sprint to expose AI agent rails for the products and platforms shipping daily.

- GitHub: [@NoBanks](https://github.com/NoBanks)
- X/Twitter: [@livingagentic](https://x.com/livingagentic)
- Site: [livingagentic.me](https://livingagentic.me), [nohumannearby.com](https://nohumannearby.com)

Open to AI engineering roles, contract or full-time, remote-only.