GetKlar MCP Server

A Model Context Protocol (MCP) server that gives AI assistants like Claude full access to the GetKlar analytics and attribution API. Import orders, refunds, COGS, logistics costs, transaction costs, and query attribution reports through natural language.

Why?

If you use GetKlar for e-commerce analytics and Claude as your AI assistant, this MCP server bridges the two. Instead of writing API scripts or using the dashboard, you just tell Claude what you need:

• "Upload these 500 orders to GetKlar"
• "Validate my refund data before submitting"
• "Get me the attribution report for last month using data-driven attribution"
• "Check the status of my last COGS upload"

Overview

This MCP server wraps GetKlar's Data Import API and Attribution API, enabling AI assistants to:

• Import orders (v1 and v2 with bundled products support)
• Import refunds
• Import COGS (Cost of Goods Sold)
• Import logistics costs
• Import transaction costs
• Query attribution reports with various models
• Check submission status

Built with TypeScript and the official MCP SDK for reliable, type-safe interactions.

Features

Data Import

• Orders: Upload/validate orders with v1 (12.2022) or v2 (07.2025) format, including bundled products support
• Refunds: Upload/validate refund data
• COGS: Upload/validate Cost of Goods Sold data
• Logistics Costs: Upload/validate shipping and logistics costs
• Transaction Costs: Upload/validate transaction fees

Attribution

• Query attribution reports with 9 different attribution models
• Support for various attribution windows (1 day, 7 day, 28 day, unlimited)
• Date breakdown by order date or touch date

Status Monitoring

• Check submission status for all data types
• View processing errors and failed IDs

Quick Start

# 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.

Installation

Prerequisites

• Node.js 18 or higher
• A GetKlar account with API access
• Claude Desktop or Claude Code

NPM Installation

npm install -g getklar-mcp

Manual Installation

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

Configuration

1. Get Your GetKlar API Token

Data Import API Token:

• Log in to your GetKlar account
• Go to Settings → Store Configurator → Data Sources
• Connect "Klar Api"
• Go to the Access Token tab
• Copy the token

Attribution API Refresh Token (optional):

• From the Klar Frontend, go to Store Settings
• Find the Attribution API section
• Copy the Refresh Token

2. Configure Claude Desktop

Add to your Claude Desktop configuration file:

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

Windows: %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. Configure Claude Code (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

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | GETKLAR_API_TOKEN | Yes | - | Your GetKlar Data Import API token | | GETKLAR_REFRESH_TOKEN | No | - | Refresh token for Attribution API (required for attribution reports) | | GETKLAR_TIMEOUT_MS | No | 30000 | Request timeout in milliseconds | | GETKLAR_LOG_LEVEL | No | info | Log level: debug, info, warn, error |

Usage Examples

With Claude Desktop / Claude Code

Once configured, you can interact with GetKlar naturally:

Orders

"Upload these orders to GetKlar" "Validate this order data before submitting" "Check the status of my last order upload" "Upload orders using the v2 format with bundled products"

Refunds

"Upload these refunds to GetKlar" "Validate my refund data" "Check refund submission status"

COGS

"Upload COGS data for these orders" "Validate COGS before submitting" "Check COGS upload status"

Logistics Costs

"Upload logistics costs for these orders" "Validate shipping costs" "Check logistics submission status"

Transaction Costs

"Upload transaction costs" "Validate transaction fee data" "Check transaction costs status"

Attribution Reports

"Get the attribution report for January 2025 using first-touch attribution" "Show me the data-driven attribution report for last month with a 7-day window" "Get attribution data broken down by touch date"

Available Tools

The MCP server provides 16 tools covering all 18 GetKlar API endpoints (Orders v1/v2 are combined via a version parameter for better UX):

Orders

| Tool | Description | API Endpoints | |------|-------------|---------------| | getklar_orders_status | Get status of last order submissions | GET /orders/status | | getklar_orders_validate | Validate orders before uploading (max 1000/batch, v1 or v2) | POST /12.2022/orders/validate + POST /07.2025/orders/validate | | getklar_orders_upload | Upload/upsert orders (max 1000/batch, v1 or v2) | POST /12.2022/orders/json + POST /07.2025/orders/json |

Refunds

| Tool | Description | API Endpoint | |------|-------------|--------------| | getklar_refunds_status | Get status of last refund submissions | GET /refunds/status | | getklar_refunds_validate | Validate refunds before uploading (max 1000/batch) | POST /04.2023/refunds/validate | | getklar_refunds_upload | Upload/upsert refunds (max 1000/batch) | POST /04.2023/refunds/json |

COGS

| Tool | Description | API Endpoint | |------|-------------|--------------| | getklar_cogs_status | Get status of last COGS submissions | GET /04.2024/cogs/status | | getklar_cogs_validate | Validate COGS before uploading (max 1000/batch) | POST /04.2024/cogs/validate | | getklar_cogs_upload | Upload/upsert COGS data (max 1000/batch) | POST /04.2024/cogs/json |

Logistics Costs

| Tool | Description | API Endpoint | |------|-------------|--------------| | getklar_logistics_status | Get status of last logistics costs submissions | GET /04.2024/logistics-costs/status | | getklar_logistics_validate | Validate logistics costs (max 1000/batch) | POST /04.2024/logistics-costs/validate | | getklar_logistics_upload | Upload/upsert logistics costs (max 1000/batch) | POST /04.2024/logistics-costs/json |

Transaction Costs

| Tool | Description | API Endpoint | |------|-------------|--------------| | getklar_transaction_status | Get status of last transaction costs submissions | GET /06.2024/transaction-costs/status | | getklar_transaction_validate | Validate transaction costs (max 1000/batch) | POST /06.2024/transaction-costs/validate | | getklar_transaction_upload | Upload/upsert transaction costs (max 1000/batch) | POST /06.2024/transaction-costs/json |

Attribution

| Tool | Description | API Endpoints | |------|-------------|---------------| | getklar_attribution_report | Get attribution report (requires refresh token) | POST /auth/token + GET /attribution/report |

Attribution Models

The Attribution API supports the following models:

| Model | Description | |-------|-------------| | first_touch | First touch gets 100% credit | | last_touch | Last touch gets 100% credit | | data_driven | Data-driven attribution (machine learning) | | linear | Equal credit to all touches | | any_click | Any click model | | any_click_unique | Unique clicks only | | u_shape | U-shaped attribution (40% first, 40% last, 20% middle) | | time_decay | Time decay (more credit to recent touches) | | marketing_mix | Marketing mix modeling |

Attribution Windows

| Window | Description | |--------|-------------| | unlimited | No time window limit | | 1_day | 1 day attribution window | | 7_day | 7 day attribution window | | 28_day | 28 day attribution window |

API Versions

Orders API

• v1 (/12.2022/orders/*): Original orders API
• v2 (/07.2025/orders/*): Updated API with bundled products support in line items

Other APIs

• Refunds: /04.2023/refunds/*
• COGS: /04.2024/cogs/*
• Logistics Costs: /04.2024/logistics-costs/*
• Transaction Costs: /06.2024/transaction-costs/*

Rate Limits

Data Import API

Standard rate limits apply. The server handles rate limiting with automatic retries.

Attribution API

• 2 requests per 30 seconds
• Maximum 31 days range per request

Error Handling

The server provides clear error messages for common issues:

• Invalid API Token: Check your token from Settings → Store Configurator → Data Sources
• Rate Limited: Server respects GetKlar's rate limits and provides retry guidance
• Validation Errors: Detailed feedback on invalid order/refund/COGS data
• Attribution API Errors: Ensure GETKLAR_REFRESH_TOKEN is set for attribution reports

Development

Setup

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

Build

npm run build

Test

npm test

Run Locally

GETKLAR_API_TOKEN=your_token npm run dev

Project Structure

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

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Guidelines

• Follow the existing code style (TypeScript, strict mode)
• Add tests for new features
• Update documentation as needed
• Keep PRs focused on a single feature/fix

Troubleshooting

"Invalid API token" error

• Ensure your token is from Settings → Store Configurator → Data Sources → Klar Api → Access Token
• Verify the token hasn't been revoked

"Authentication failed" for Attribution API

• Ensure GETKLAR_REFRESH_TOKEN is set
• Get the refresh token from Store Settings in the Klar Frontend
• The refresh token is used to obtain a short-lived access token (5 min TTL)

"Rate limited" responses

• Attribution API has strict limits: 2 requests per 30 seconds
• The server automatically handles rate limiting with retries
• For bulk operations, allow time between requests

Tools not appearing in Claude

• Restart Claude Desktop after config changes
• Check the config file syntax is valid JSON
• Verify the server starts without errors: GETKLAR_API_TOKEN=test npx getklar-mcp

Connection timeout

• Check your network connection
• Try increasing GETKLAR_TIMEOUT_MS
• Verify GetKlar's API status

API Reference

This server wraps GetKlar's APIs. For detailed documentation:

• GetKlar API Introduction
• Attribution API Documentation
• Transaction Costs Documentation
• OpenAPI Spec UI

License

MIT License - see LICENSE for details.

Acknowledgments

• GetKlar for their comprehensive analytics API
• Anthropic for the MCP specification
• The MCP community for tooling and examples

Note: This is an unofficial integration. GetKlar is a trademark of its respective owner.