Klarna MCP server: connect Claude to Klarna orders, payouts and disputes

Klarna is the payment method a large share of Nordic shoppers pick at checkout, and the data behind it lives in three places: Order Management for what was authorized and captured, Settlements for what actually reached your bank, and Disputes for what customers are contesting. Finance and e-commerce teams spend real hours stitching those together. klarna-mcp lets Claude, Cursor or any other MCP client read all three, so the stitching becomes a question.

We built it because Klarna's own MCP server covers product search for shoppers, not the merchant side. The code is open source at github.com/Walma-Labs/klarna-mcp under the MIT licence. It is unofficial and not affiliated with Klarna.

What it can read

All amounts, in and out, are integers in minor units: 10000 means 100.00 SEK.

Three things about Klarna's API are worth telling the agent, and the tool descriptions already do:

• Order ids are Klarna's ids, not your shop's order number. Your number is in merchant_reference1 on the order.
• Transactions have no date filter. Find the payouts for a period first, then list transactions per payout.
• Refunds have no list endpoint. They are listed on the order itself, which get_order returns.

What it can change, and only when you say so

Five write tools exist: capture_order (full or partial), refund_order, extend_authorization_time, cancel_order and release_remaining_authorization. They are not registered unless the environment sets KLARNA_ENABLE_WRITES=true, so without that flag the model cannot call them whatever the prompt says.

When they are on, every write sends a Klarna-Idempotency-Key header. The tool returns the key it used, so a timed-out capture can be retried with the same key and Klarna executes it at most once. Captures, refunds, cancels and releases carry the MCP destructiveHint annotation, which makes clients that honour annotations ask before running them. Capture is marked destructive on purpose: in API terms it only adds, but it charges a customer.

Setup

1. Get an API credential. In the Klarna Merchant Portal, create a credential for the environment you want. Test keys start with klarna_test_api_, live keys with klarna_live_api_. Create a separate credential for the agent so you can revoke it on its own.

2. Install. The package is not on npm, so clone and build it (Node 20 or newer):

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

3. Add it to Claude Code. Use the absolute path to your clone:

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

Claude Desktop and Cursor take the same thing as JSON, in claude_desktop_config.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"
      }
    }
  }
}

KLARNA_REGION is eu, na or oc, and KLARNA_ENV is playground or production. Both default to the safe choice, the EU playground. General client instructions are in our guides for Claude Code, Claude Desktop and Cursor.

What to ask it

• "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?"
• "Show order <klarna order id>: what is authorized, what is captured, and when does the authorization expire?"
• "Which orders in last week's payouts were refunded, and how much did returns cost us?"
• "List open disputes from the last 30 days, grouped by reason, with the closest deadlines first."
• "Download the payout report for <payment reference> and reconcile it against this export from our shop."

The reconciliation questions are where it earns its keep. Combine it with Stripe or Shopify and one session can trace an order from the shop, through the payment provider, to the bank line.

Status and limits

klarna-mcp is built endpoint by endpoint from Klarna's published API reference and covered by 42 tests against mocked responses. It has not yet been verified against a live Klarna account. Run it on the playground first and open an issue if anything does not match. Known limits:

• Disputes need your merchant account to be enrolled in Klarna's Disputes API v4. An empty list can mean you are not enrolled.
• Klarna's Disputes v4 reference lists only EU hosts, so disputes in North America and Oceania are untested.
• Left out on purpose: PDF settlement reports, order updates (amounts, lines, addresses), due-date extensions, dispute responses and creating payment sessions.

Running it for a team

A Klarna credential reads every order and payout on the account, and with writes on it can move money. On a laptop that is one leaked config file away from a problem. The repository includes a stateless HTTP entrypoint (dist/http.js) for hosting the server centrally, and it has no authentication of its own on purpose: it belongs behind a gateway that authenticates each user, keeps the credential out of their hands, requires approval for writes and logs every call.

That is how Walma runs it: inside the customer's own EU region, next to Shopify, Stripe and the shipping servers in our e-commerce package. The connection is also listed in our MCP directory.