Getklar MCP

GetKlar MCP 服务器

](https://www.npmjs.com/package/getklar-mcp)  ](https://nodejs.org/)

A. 模型上下文协议（MCP） 服务器，让像克劳德这样的人工智能助手可以完全访问 GetKlar 分析和归因API。通过自然语言输入订单、退款、销货成本、物流成本、交易成本和查询归因报告。

为什么？

如果您使用GetKlar进行电子商务分析，并使用Claude作为您的人工智能助手，则此MCP服务器将两者连接起来。您只需告诉Claude您需要什么，而不是编写API脚本或使用仪表板：

• “将这500个订单上传到GetKlar”
• “提交前验证我的退款数据”
• “使用数据驱动的归因给我上个月的归因报告”
• “检查我上次COGS上传的状态”

概述

此MCP服务器包装GetKlar的数据导入API和归因API，使人工智能助手能够：

• 进口订单（支持捆绑产品的v1和v2）
• 进口退税
• 进口销货成本
• 进口物流成本
• 进口交易成本
• 查询各种模型的归因报告
• 检查提交状态

使用TypeScript和官方MCP SDK构建，实现可靠、类型安全的交互。

特性

数据导入

• 订单：上传/验证v1（12.2022）或v2（07.2025）格式的订单，包括捆绑产品支持
• 退款：上传/验证退款数据
• 销售成本：上传/验证销售成本数据
• 物流成本：上传/验证运输和物流成本
• 交易成本：上传/验证交易费用

归因

• 使用9种不同的归因模型查询归因报告
• 支持多种归因窗口（1天、7天、28天，无限制）
• 按订单日期或接触日期细分的日期

状态监测

• 检查所有数据类型的提交状态
• 查看处理错误和失败的ID

快速开始

# Install
npm install -g getklar-mcp

# Add to Claude Code
claude mcp add getklar-mcp -e GETKLAR_API_TOKEN=your_token_here

# Done. Ask Claude anything about your GetKlar data.

安装

先决条件

• Node.js 18或更高版本
• 具有API访问权限的GetKlar帐户
• 克劳德桌面或克劳德代码

NPM安装

npm install -g getklar-mcp

手动安装

git clone https://github.com/doinglean/getklar-mcp.git
cd getklar-mcp
npm install
npm run build

配置

1.获取GetKlar API代币

数据导入API令牌：

• 登录到您的 GetKlar帐户
• 转到“设置”→ 商店配置器→ 数据源
• 连接“Klar Api”
• 转到访问令牌选项卡
• 复制令牌

归因API刷新令牌（可选）：

• 从Klar前端，转到商店设置
• 查找归因API部分
• 复制刷新令牌

2.配置克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "getklar": {
      "command": "npx",
      "args": ["getklar-mcp"],
      "env": {
        "GETKLAR_API_TOKEN": "your_api_token_here",
        "GETKLAR_REFRESH_TOKEN": "your_refresh_token_here"
      }
    }
  }
}

3.配置克劳德代码（CLI）

# Add the MCP server
claude mcp add getklar-mcp -e GETKLAR_API_TOKEN=your_token_here

# Or with both tokens for Attribution API support
claude mcp add getklar-mcp -e GETKLAR_API_TOKEN=your_token_here -e GETKLAR_REFRESH_TOKEN=your_refresh_token_here

环境变量

使用示例

使用克劳德桌面/克劳德代码

配置后，您可以自然地与GetKlar交互：

订单

“将这些订单上传到GetKlar” “提交前验证此订单数据” “检查我上次订单上传的状态” “使用捆绑产品的v2格式上传订单”

退款

“将这些退款上传到GetKlar” “验证我的退款数据” “检查退款提交状态”

销售成本

“上传这些订单的COGS数据” “提交前验证COGS” “检查COGS上传状态”

物流成本

“上传这些订单的物流成本” “验证运费” “检查物流提交状态”

交易成本

“上传交易成本” “验证交易费用数据” “检查交易成本状态”

归因报告

“使用首次点击归因获取2025年1月的归因报告” “给我看上个月的数据驱动归因报告，有7天的窗口期” “获取按触摸日期细分的归因数据”

可用工具

MCP服务器提供 16工具 覆盖所有18个GetKlar API端点（订单v1/v2通过 version 更好的用户体验参数）：

订单

退款

销售成本

物流成本

交易成本

归因

归因模型

归因API支持以下模型：

归因窗口

API版本

订单API

• 第1版 (/12.2022/orders/*)：API原始订单
• 第2版 (/07.2025/orders/*)：更新API，在行项目中提供捆绑产品支持

其他API

• 退款: /04.2023/refunds/*
• 销售成本: /04.2024/cogs/*
• 物流成本: /04.2024/logistics-costs/*
• 交易成本: /06.2024/transaction-costs/*

速率限制

数据导入API

标准费率限制适用。服务器通过自动重试来处理速率限制。

归因API

• 每30秒2个请求
• 每个请求最多31天

错误处理

服务器为常见问题提供明确的错误消息：

• API令牌无效：从设置中检查您的令牌→ 商店配置器→ 数据源
• 速率限制：服务器尊重GetKlar的速率限制，并提供重试指导
• 验证错误：关于无效订单/退款/COGS数据的详细反馈
• 归因API错误：确保为归因报告设置GETKLAR_REFRESH_TOKEN

发展

设置

git clone https://github.com/doinglean/getklar-mcp.git
cd getklar-mcp
npm install

构建

npm run build

测试

npm test

在本地运行

GETKLAR_API_TOKEN=your_token npm run dev

项目结构

src/
├── index.ts                    # Entry point & MCP server setup
├── api/
│   └── client.ts               # GetKlar API client
├── tools/
│   ├── index.ts                # Tool registry
│   ├── orders.ts               # Orders tools
│   ├── refunds.ts              # Refunds tools
│   ├── cogs.ts                 # COGS tools
│   ├── logistics-costs.ts      # Logistics costs tools
│   ├── transaction-costs.ts    # Transaction costs tools
│   └── attribution.ts          # Attribution tools
└── utils/
    ├── logger.ts               # Structured logging
    └── validation.ts           # Input validation

贡献

欢迎投稿！请按照以下步骤操作：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

指南

• 遵循现有的代码风格（TypeScript，严格模式）
• 为新功能添加测试
• 根据需要更新文档
• 让PR专注于单一功能/修复

故障排除

“API令牌无效”错误

• 确保您的令牌来自设置→ 商店配置器→ 数据源→ Klar Api→ 访问令牌
• 验证令牌是否未被撤销

归因API的“身份验证失败”

• 确保GETKLAR_REFRESH_TOKEN已设置
• 从Klar前端的商店设置中获取刷新令牌
• 刷新令牌用于获取短期访问令牌（5分钟TTL）

“限速”响应

• 归因API有严格的限制：每30秒2个请求
• 服务器通过重试自动处理速率限制
• 对于批量操作，允许请求之间有时间间隔

工具未出现在Claude中

• 配置更改后重新启动Claude Desktop
• 检查配置文件语法是否为有效的JSON
• 验证服务器启动时没有错误： GETKLAR_API_TOKEN=test npx getklar-mcp

连接超时

• 检查您的网络连接
• 尝试增加GETKLAR_TIMEOUT_MS
• 验证GetKlar的API状态

api参考

此服务器封装GetKlar的API。详细文档：

• GetKlar API 介绍
• 归因API文档
• 交易成本文件
• OpenAPI规范用户界面

许可证

MIT许可证-请参阅 许可证 了解详情。

致谢

• GetKlar 用于他们的综合分析API
• Anthropic 对于MCP规范
• MCP社区提供工具和示例

注意：这是一个非官方集成。GetKlar是其各自所有者的商标。