AI导哈

Gorgias帮助台连接服务

连接Claude到Gorgias帮助台的MCP服务器，提供票务查询、客户体验指标监控、事件分类和标签管理功能。

  • by cacosat
  • JavaScript
  • 混合部署
  • 更新于
在 GitHub 查看 cacosat/test-mcp

使用说明

Gorgias MCP服务器

将Claude连接到您的MCP服务器 高尔吉亚 帮助台——查询工单、监控CX指标、对事件进行分类并实时管理标签。

可用工具

工具 描述 类型
list_tickets 列出带有分页、排序和客户/视图过滤的门票 阅读
get_ticket 获取包含消息、标签和自定义字段的单票 阅读
create_ticket 创建新票证 写入
update_ticket 更新状态、受让人、自定义字段（偶发事件L1/L2/L3）、标签 写入
add_message_to_ticket 在工单上添加回复或内部注释 写
list_customers 列出具有可选电子邮件过滤器的客户 阅读
get_customer 按ID获取单个客户 阅读
get_ticket_fields 获取自定义字段定义（Incidencias分类下拉菜单） 阅读
get_satisfaction_stats 获取个人CSAT调查回复 阅读
get_ticket_stats 获取日期范围的首次响应时间或解决时间 阅读
list_tags 列出所有可用标签 阅读
manage_tags 添加或删除票证上的标签 写入

先决条件

  • Node.js v18+
  • Gorgias API凭据（Gorgias帐户中的设置>REST API）

设置

git clone https://github.com/cacosat/test-mcp.git
cd test-mcp
npm install
cp .env.example .env

编辑 .env 使用您的凭据：

GORGIAS_DOMAIN=your-subdomain.gorgias.com
GORGIAS_USERNAME=your-email@example.com
GORGIAS_API_KEY=your-api-key
READ_ONLY=false

测试

使用 MCP检查员 交互式测试工具：

npx @modelcontextprotocol/inspector node src/index.js

这将打开一个web UI，您可以在其中调用任何工具并查看响应。尝试 list_tickets 和 {"limit": 5} 以验证您的连接。

客户端配置

克劳德桌面

添加 claude_desktop_config.json:

  • 雨衣： ~/Library/Application Support/Claude/claude_desktop_config.json
  • 窗户： %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "gorgias": {
      "command": "node",
      "args": ["/absolute/path/to/test-mcp/src/index.js"],
      "env": {
        "GORGIAS_DOMAIN": "your-subdomain.gorgias.com",
        "GORGIAS_USERNAME": "your-email@example.com",
        "GORGIAS_API_KEY": "your-api-key",
        "READ_ONLY": "true"
      }
    }
  }
}

克劳德代码

添加 .claude/settings.json （项目级或 ~/.claude/settings.json 全球）：

{
  "mcpServers": {
    "gorgias": {
      "command": "node",
      "args": ["/absolute/path/to/test-mcp/src/index.js"],
      "env": {
        "GORGIAS_DOMAIN": "your-subdomain.gorgias.com",
        "GORGIAS_USERNAME": "your-email@example.com",
        "GORGIAS_API_KEY": "your-api-key",
        "READ_ONLY": "true"
      }
    }
  }
}

只读模式

集 READ_ONLY=true 禁用所有写入操作。仅注册了8个读取工具，Claude无法创建、更新或修改任何数据。建议用于初始部署。

速率限制和缓存

  • 速率限制： 在Gorgias的HTTP 429上，以指数回退（1s、2s、4s）重试最多3次。尊重 Retry-After 头球
  • 缓存： 答复来自 /stats/* 和 /custom-fields 在内存中缓存5分钟，以减少报告生成期间的API调用。

建筑

src/
  index.js              Entry point — env validation, stdio transport
  gorgias-client.js     HTTP client — auth, rate limiting, caching
  server.js             MCP server — tool registration, READ_ONLY gating
  tools/
    tickets.js          list, get, create, update, add message (5 tools)
    customers.js        list, get (2 tools)
    fields.js           get custom fields (1 tool)
    stats.js            satisfaction surveys, ticket stats (2 tools)
    tags.js             list, manage (2 tools)

看 DOCS.md 以获取带有参数、API映射和故障排除的完整工具参考。

生产部署

步骤1：使用READ_ONLY进行验证

与一起跑步 READ_ONLY=true 并根据您的实时Gorgias数据测试所有8个读取工具。确认 list_tickets, get_ticket_fields, get_ticket_stats，以及 get_satisfaction_stats 返回正确的结果。这是当前状态——如果您已经测试过，则不需要更改。

步骤2：启用写入工具

一旦自信，就设定 READ_ONLY=false 并重新启动克劳德桌面。首先在非关键工单上测试写入工具：

  1. manage_tags --最安全的写入操作。添加一个测试标签，然后将其删除。
  2. update_ticket --尝试在测试票上设置一个自定义字段（Incidencias）。
  3. add_message_to_ticket --添加内部注释（客户看不到）。
  4. create_ticket --创建测试票并立即关闭。

步骤3：创建Gorgias视图进行过滤

自从 list_tickets 不支持按状态/频道/标签进行特殊过滤，请在Gorgias中创建视图来覆盖您的常见查询：

  • 本周开放门票 --过滤器：状态=打开，最近7天创建
  • 未分类门票 --过滤器：偶发事件字段为空
  • 从Vambe升级 --筛选器：标记包含 api 或 reuse
  • 按国家 --每个国家/一体化一个视图（智利、墨西哥、秘鲁）

记下每个视图的ID（在Gorgias中查看时在URL中可见），并将其传递给 list_tickets 通过 view_id.

步骤4：安全凭据

供团队或生产使用：

  • 永不承诺 .env --它已经在里面了 .gitignore
  • 旋转API键 -为MCP服务器创建一个独立于个人密钥的专用Gorgias API密钥
  • 限制权限 -如果Gorgias支持作用域API密钥，则在不需要写访问时使用只读密钥
  • 秘密管理员 --对于共享/部署的环境，从secrets管理器（AWS secrets manager、1Password CLI等）加载凭据，而不是 .env 文件

步骤5：部署到Cloudflare Workers（远程访问）

将服务器部署到Cloudflare Workers，这样您的团队就可以在不进行本地设置的情况下进行连接。服务器使用 可流式传输的HTTP 运输（MCP规范2025-03-26）。

先决条件： Cloudflare帐户 + 牧马人命令行界面 已认证(npx wrangler login).

设置秘密：

npx wrangler secret put GORGIAS_DOMAIN
npx wrangler secret put GORGIAS_USERNAME
npx wrangler secret put GORGIAS_API_KEY
npx wrangler secret put READ_ONLY

每个命令都会提示您以交互方式输入值（机密永远不会存储在代码中）。

部署：

npm run deploy

您的服务器将在 https://gorgias-mcp.<your-account>.workers.dev/mcp.

从克劳德代码连接：

claude mcp add gorgias --transport streamable-http https://gorgias-mcp.<your-account>.workers.dev/mcp

当地工人发展：

cp .dev.vars.example .dev.vars
# Fill in your credentials in .dev.vars
npm run dev:worker

已知限制（第1阶段——无授权）：

  • Worker端点上没有身份验证——任何具有URL的人都可以调用它。仅适用于内部测试。
  • 所有用户共享一个Gorgias API密钥。Gorgias费率限制（基本计划约2个要求/秒）适用于密钥，而不是每个用户。一个忙碌的团队可能会达到极限。
  • 耐用对象与Workers免费层分开计费（约0.15美元/百万请求）。对于一个小团队来说，这基本上是免费的。

第六步：克劳德企业——与您的组织分享

对于Claude Enterprise/Team帐户，管理员可以使MCP服务器对所有工作区成员可用：

  1. 首选 组织设置>连接器>添加自定义连接器
  2. 输入Worker URL: https://gorgias-mcp.<your-account>.workers.dev/mcp
  3. 对于阶段1（authless），将OAuth字段留空
  4. 团队成员通过以下方式为每次对话启用连接器 + 按钮> 连接器 切换

对于生产（OAuth）： claude.ai web连接器UI需要OAuth 2.1，不支持裸承载令牌。要添加OAuth，请执行以下操作：

  1. 使用Cloudflare的OAuth模板作为参考： cloudflare/ai/demos/remote-mcp-github-oauth
  2. 添加OAuth提供者（GitHub、Google或通过Auth0/Stytch/WorkOS自定义）
  3. 在Claude Enterprise连接器设置中配置OAuth客户端ID/密钥

对于 Claude 代码命令行工具 用户，无授权版本可以直接工作，不需要OAuth。

步骤7：迁移统计数据API（2026年12月之前）

这 POST /api/stats/{metric} 端点是遗留的，并且将是 2026年12月31日日落。在此日期之前，迁移 get_ticket_stats 对于新 POST /api/reporting/stats 终点。看 Gorgias API文档 对于新格式。

下一步可能采取的措施

  • 添加OAuth --保护Worker端点，以便与您的Claude Enterprise组织一起用于生产
  • Shopify MCP服务器 --为Shopify订单数据添加一个单独的MCP服务器，让Claude将工单与订单进行交叉引用
  • 提示模板 --为重复工作流创建系统提示：每周CX报告、票分类器、CSAT监视器、异常检测器
  • 预定报告 --使用克劳德代码 /schedule 自动运行每周CX报告的命令

相关 MCP