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.