Skip to main content
Glama

klarna-mcp: an MCP server for Klarna's merchant APIs

A small Model Context Protocol server that gives Claude, Cursor, Claude Code and any other MCP client access to Klarna's merchant APIs: orders, captures, refunds, payouts, settlement transactions, disputes and payment sessions.

It is read-only by default. Write tools (capture, refund, extend authorization, cancel, release) exist, but they are not even registered unless you set KLARNA_ENABLE_WRITES=true.

Built by Walma AI. There is a longer write-up in our guide: Klarna MCP. For how e-commerce teams use servers like this one, see AI for e-commerce.

Unofficial. This project is not made, endorsed or supported by Klarna, and is not affiliated with Klarna Bank AB. "Klarna" is a trademark of Klarna Bank AB, used here only to describe which API the server talks to.

Status: built against Klarna's documented API; not yet verified against a live Klarna environment. Try it on the playground first and please report anything that does not match.

Tools

All money amounts, in and out, are integers in minor units of the currency: 10000 means 100.00 SEK, EUR or USD.

Read tools (always available)

Tool

Klarna endpoint

What it does

get_order

GET /ordermanagement/v1/orders/{order_id}

Order status, amounts (authorized, captured, refunded, remaining), expiry, lines, captures and refunds

list_captures

GET /ordermanagement/v1/orders/{order_id}/captures

All captures on an order

get_capture

GET /ordermanagement/v1/orders/{order_id}/captures/{capture_id}

One capture

get_refund

GET /ordermanagement/v1/orders/{order_id}/refunds/{refund_id}

One refund (all refunds are listed on the order)

list_payouts

GET /settlements/v1/payouts

Payouts with totals, by date range and currency, paginated

get_payout

GET /settlements/v1/payouts/{payment_reference}

One payout by the reference on your bank statement

get_payout_summary

GET /settlements/v1/payouts/summary

Totals per currency for a date range

list_transactions

GET /settlements/v1/transactions

Settlement transactions by payout and/or order, paginated

get_payout_report_csv

GET /settlements/v1/reports/payout-with-transactions

One payout with its transactions, as CSV text

get_payouts_summary_report_csv

GET /settlements/v1/reports/payouts-summary-with-transactions

All payouts and transactions in a date range, as CSV text

list_disputes

GET /v4/payment/disputes

Disputes by order, state, reason, reference and dates, cursor-paginated

get_dispute

GET /v4/payment/disputes/{payment_dispute_id}

One dispute with its requests and deadlines

get_payment_session

GET /payments/v1/sessions/{session_id}

A Klarna Payments session (never creates or updates one)

Write tools (only with KLARNA_ENABLE_WRITES=true)

Tool

Klarna endpoint

Annotation

capture_order

POST /ordermanagement/v1/orders/{order_id}/captures

destructive

refund_order

POST /ordermanagement/v1/orders/{order_id}/refunds

destructive

extend_authorization_time

POST /ordermanagement/v1/orders/{order_id}/extend-authorization-time

not destructive

cancel_order

POST /ordermanagement/v1/orders/{order_id}/cancel

destructive

release_remaining_authorization

POST /ordermanagement/v1/orders/{order_id}/release-remaining-authorization

destructive

Read tools carry readOnlyHint: true. Write tools carry readOnlyHint: false, and every write that moves money or cannot be undone carries destructiveHint: true, so clients that honour annotations ask before running them. Capture is marked destructive too: it is an additive call in API terms, but it charges a customer.

Related MCP server: Amiqus MCP server

Safety model

  1. Read-only unless you say otherwise. Without KLARNA_ENABLE_WRITES=true (exactly true) the write tools do not exist on the server, so the model cannot call them, whatever the prompt says.

  2. Playground first. KLARNA_ENV defaults to playground. Point it at production only after you have watched the tools behave on test orders.

  3. Idempotency on every write. Each write sends a Klarna-Idempotency-Key header. The tool generates one if you do not pass it and returns it in the result; retry a failed or timed-out write with the same idempotency_key and Klarna executes it at most once (Klarna keeps keys for 24 hours).

  4. Credentials stay out of the conversation. They are read from the environment and sent only in the Authorization header. Error messages are built from Klarna's error_code, error_messages and correlation_id, and anything that looks like a credential is redacted before it reaches the model.

  5. Use a dedicated credential. Create a separate API credential for the agent in the Klarna Merchant Portal so you can revoke it on its own.

Setup

1. Get API credentials

In the Klarna Merchant Portal, create an API credential for the environment you want. Klarna's keys say which one they belong to: klarna_test_api_... is for the playground, klarna_live_api_... for production. When you create the credential, Klarna shows a username (a UUID) next to the API key; use the username as KLARNA_USERNAME and the API key as KLARNA_PASSWORD, or set only KLARNA_API_KEY.

2. Install

The package is not on npm. Clone and build it:

git clone https://github.com/Walma-Labs/klarna-mcp.git
cd klarna-mcp
npm install
npm run build

This gives you dist/stdio.js. Node 20 or newer is required.

3. Configure

Variable

Default

Meaning

KLARNA_USERNAME

API credential username

KLARNA_PASSWORD

API credential password (the API key or shared secret)

KLARNA_API_KEY

Alternative to the two above: a klarna_<live|test>_api_... key, sent as Authorization: Basic <API key> as Klarna documents it

KLARNA_REGION

eu

eu, na or oc

KLARNA_ENV

playground

playground or production

KLARNA_ENABLE_WRITES

off

true registers the write tools

Region and environment map to Klarna's documented hosts:

Production

Playground

eu

https://api.klarna.com

https://api.playground.klarna.com

na

https://api-na.klarna.com

https://api-na.playground.klarna.com

oc

https://api-oc.klarna.com

https://api-oc.playground.klarna.com

4. Add it to your client

Use the absolute path to your clone.

Claude Code

claude mcp add --transport stdio klarna \
  -e KLARNA_USERNAME=your-username \
  -e KLARNA_PASSWORD=your-password \
  -e KLARNA_REGION=eu \
  -e KLARNA_ENV=playground \
  -- node /absolute/path/to/klarna-mcp/dist/stdio.js

Add -e KLARNA_ENABLE_WRITES=true only when you want the write tools.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "klarna": {
      "command": "node",
      "args": ["/Users/you/klarna-mcp/dist/stdio.js"],
      "env": {
        "KLARNA_USERNAME": "your-username",
        "KLARNA_PASSWORD": "your-password",
        "KLARNA_REGION": "eu",
        "KLARNA_ENV": "playground"
      }
    }
  }
}

Cursor (.cursor/mcp.json or ~/.cursor/mcp.json)

{
  "mcpServers": {
    "klarna": {
      "command": "node",
      "args": ["/Users/you/klarna-mcp/dist/stdio.js"],
      "env": {
        "KLARNA_USERNAME": "your-username",
        "KLARNA_PASSWORD": "your-password",
        "KLARNA_REGION": "eu",
        "KLARNA_ENV": "playground"
      }
    }
  }
}

Desktop clients do not expand ~ or inherit your shell's PATH, so use absolute paths (and the absolute path to node if it is not found).

Running it as a remote server

dist/http.js is a stateless streamable-HTTP entrypoint for hosting the server centrally. It listens on PORT (default 8080) with a /healthz endpoint and has no auth of its own: anyone who reaches the port uses your Klarna credentials. Only run it behind a gateway that authenticates callers. Programmatic hosts can import { createKlarnaServer } from "klarna-mcp" and mount it on any transport.

Using it

Example prompts for an e-commerce or finance team:

  • "Show me order <klarna order id>: what is authorized, what is captured, and when does the authorization expire?"

  • "Sum up our Klarna payouts for September per currency: sales, fees, returns and what actually hit the bank."

  • "Get payout <payment reference> and list its transactions. Which fees and returns are in it?"

  • "Which settlement transactions belong to order <klarna order id>, and in which payout did the sale land?"

  • "List open disputes created in the last 30 days, grouped by reason, and tell me which deadlines are closest."

  • "Download the payout report CSV for <payment reference> and reconcile it against this export from our shop."

  • With writes on, on the playground: "Capture 450.00 SEK of order <id> for the two lines that shipped today, with DHL tracking number 123."

Things to tell the agent:

  • Order ids are Klarna's order ids, not your shop's order number. Your number is merchant_reference1 on the order.

  • Settlements dates are date-times. A bare date means midnight, so ask for 2026-09-30T23:59:59Z to include the last day.

  • Transactions have no date filter in Klarna's API. Find the payouts for a period first, then list transactions per payout.

  • Disputes need enrollment. Klarna's Disputes API v4 requires your merchant account to be enrolled; an empty list can mean you are not. Klarna's v4 reference lists only the EU hosts.

Development

npm install
npm run build && npm test
KLARNA_USERNAME=... KLARNA_PASSWORD=... node dist/stdio.js

Tests drive the real MCP wire and the real HTTP client against a mocked fetch, so they need no network or credentials. Try the server interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/stdio.js

Sources

Every endpoint, field and header comes from Klarna's published API reference:

Left out on purpose: the PDF settlement reports (binary), order updates (amount, lines, addresses, references, shipping info), due-date extensions and customer send-outs, dispute responses and evidence uploads, and creating payment sessions or orders.

License

MIT. Copyright (c) 2026 Walma AI AB.

Available Tools

13 tools
get_captureGet captureB
Read-onlyIdempotent

Get one capture on a Klarna order by capture_id (amounts in minor units).

Inputs: order_id (required), capture_id (required).

get_disputeGet disputeA
Read-onlyIdempotent

Get one dispute in its current state, including its requests, deadlines and evidence history (Klarna Disputes API v4).

Inputs: payment_dispute_id (required).

get_orderGet orderA
Read-onlyIdempotent

Get a Klarna order: status (AUTHORIZED, PART_CAPTURED, CAPTURED, CANCELLED, EXPIRED, CLOSED), order_amount, captured_amount, refunded_amount, remaining_authorized_amount, expires_at, order lines, captures, refunds, merchant references and addresses. Amounts in minor units. This is also where refunds for an order are listed (Klarna has no separate list-refunds endpoint).

Inputs: order_id (required).

get_payment_sessionGet payment sessionA
Read-onlyIdempotent

Read a Klarna Payments session by session_id: status, order amount and lines (minor units), purchase country/currency, payment method categories and expiry. Useful when debugging a checkout that never became an order. This server never creates or updates sessions.

Inputs: session_id (required).

get_payoutGet payoutA
Read-onlyIdempotent

Get one Klarna payout by its payment_reference (the reference on your bank statement), with all totals in minor units.

Inputs: payment_reference (required).

get_payout_report_csvPayout report (CSV)A
Read-onlyIdempotent

Download the settlement report for one payout, with all its transactions, as CSV text (Klarna's documented settlement report format). Use for reconciliation in a spreadsheet.

Inputs: payment_reference (required).

get_payouts_summary_report_csvPayouts summary report (CSV)A
Read-onlyIdempotent

Download a CSV report of all payouts and their transactions between two dates. Can be large: keep the range short (a month or less).

Inputs: end_date (required), start_date (required).

get_payout_summaryPayout summaryA
Read-onlyIdempotent

Summary of all payouts in a date range, one entry per currency: total sales, fees, returns, commissions, holdback, releases, reversals, tax and settlement amount (minor units). Good for monthly reconciliation.

Inputs: end_date (required), start_date (required), currency_code.

get_refundGet refundA
Read-onlyIdempotent

Get one refund on a Klarna order by refund_id: refunded_amount (minor units), time, description, reference and order lines. To list all refunds, use get_order.

Inputs: order_id (required), refund_id (required).

list_capturesList capturesB
Read-onlyIdempotent

List all captures on a Klarna order, with captured_amount and refunded_amount (minor units), capture time, references and shipping info.

Inputs: order_id (required).

list_disputesList disputesA
Read-onlyIdempotent

List customer disputes (Klarna Disputes API v4) filtered by order, state, reason, purchase reference and date ranges. States: INITIATED, REPRESENTMENT, PRE_ARBITRATION, ARBITRATION, CLOSED. Cursor pagination: pass pagination.last_item from the previous page as starting_after. Your merchant account must be enrolled for the Disputes API; an empty list can also mean it is not.

Inputs: size, state, reason, sort_by, +11 more.

list_payoutsList payoutsA
Read-onlyIdempotent

List Klarna payouts (settlements to your bank account) with totals per payout: sale, fee, return, holdback, reversal, tax and settlement amounts, all in minor units. Filter by payout date range and currency. Paginated with size/offset; the response has a pagination object with total.

Inputs: size, offset, end_date, start_date, +1 more.

list_transactionsList settlement transactionsA
Read-onlyIdempotent

List settlement transactions (SALE, RETURN, FEE, REVERSAL and so on) with amount in minor units, order id, capture/refund ids, merchant references and payout reference. Filter by payout (payment_reference) and/or Klarna order_id. Klarna's API has no date filter here: to get a period, find the payouts with list_payouts and pass each payment_reference. Paginated with size/offset.

Inputs: size, offset, order_id, payment_reference.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools target distinct resources (disputes, sessions, orders, captures, refunds, payouts, transactions). The main ambiguity is the payout cluster: get_payout_report_csv (one payout) vs get_payouts_summary_report_csv (range report) and list_payouts vs get_payout_summary differ by subtle wording. Descriptions mostly disambiguate, but the CSV pair could be misselected at a glance.

    Naming Consistency5/5

    Names follow a consistent get_/list_ verb_noun pattern across the set (list_disputes, get_dispute, get_order, list_captures, get_capture, get_refund, list_payouts, etc.). The only minor wrinkle is payout (singular) vs payouts (plural) in the summary/report names, but conventions remain predictable.

    Tool Count5/5

    13 tools is well-scoped for a Klarna merchant domain spanning disputes, payments sessions, orders, captures, refunds, payouts and settlement reports. Each tool maps to a distinct operation and none feels redundant or filler.

    Completeness3/5

    Read coverage is broad, but the surface is entirely read-only: there are no order creation, capture, refund, cancel or release operations, and disputes expose no actions (submit evidence, represent, arbitrate). This leaves obvious lifecycle gaps for a merchant integration, though it may be intentional for reconciliation-focused use.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables sellers to interact with Amazon Selling Partner API and Advertising API data—orders, inventory, pricing, ads, reports, and more—through MCP clients like Claude and Cursor.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables Claude, ChatGPT and other MCP clients to read an Amiqus ID account—clients, onboarding records and steps, check results, templates, case status counts and webhooks—and, when writes are enabled, create records.
      9
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables MCP clients such as Claude Code, Claude Desktop, and Cursor to read a user's own Open Finance Brasil data through Meu Pluggy — accounts, balances, transactions, card bills, investments, and spending by category — while remaining strictly read-only and never moving money or storing data.
      7
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude to manage orders, stock, purchase orders, pickwaves, and channel listings in a user's own e-commerce account through 104 MCP tools, with dry-run defaults for writes.
      MIT