Gorgias

This MCP server provides a bridge to the Gorgias helpdesk API, exposing tools and resources for managing tickets and customers. It offers a set of MCP actions under the Tickets and Customers namespaces, such as listing tickets, retrieving a specific ticket, creating a ticket, and adding messages to existing tickets, as well as listing and fetching customers. The server supports two authentication methods: API key authentication (username and API key) and OAuth token authentication, configurable via environment variables. You can quickly test and experiment with the available tools using the MCP Inspector.

Prerequisites:

• Node.js (LTS) and npm
• Git
• Access to Gorgias credentials (API key or OAuth token)

Installation steps:

# 1. Clone the repository
git clone https://github.com/your-org/mattcoatsworth-gorgias-mcp-server.git
cd mattcoatsworth-gorgias-mcp-server

# 2. Install dependencies
npm install

Configure environment variables:

# Create a .env file based on the example provided by the repo
# Example using API key authentication
GORGIAS_DOMAIN=your-domain.gorgias.com
GORGIAS_USERNAME=your-username
GORGIAS_API_KEY=your-api-key

# Example using OAuth authentication (alternative)
# GORGIAS_DOMAIN=your-domain.gorgias.com
# GORGIAS_ACCESS_TOKEN=your-oauth-access-token

Run the server in development mode:

# Start the server (development mode if a dev script is defined)
npm run dev

Optionally, test with MCP Inspector if available:

npm run inspect

Notes:

• The server supports two authentication methods: API key ( username + API key ) and OAuth token. Set the desired method in the .env file.
• Available tools include: list_tickets, get_ticket, create_ticket, add_message_to_ticket, list_customers, get_customer.
• Resources exposed for quick access include gorgias://tickets and gorgias://ticket/{id}. Ensure proper URL handling in your MCP Inspector or client.
• If you encounter API rate limits, consider spacing requests or using OAuth tokens with appropriate scopes.
• Ensure GORGIA_DOMAIN is set to the correct Gorgias subdomain (e.g., your-domain.gorgias.com).
• The MCP server may require CORS or proxy configuration depending on your environment; adjust accordingly if you run behind a reverse proxy.