klarna-mcp
Provides tools for interacting with Klarna's merchant APIs, covering order management (retrieving order status, amounts, and lines), captures, refunds, payouts and settlement transactions (including payout summaries and CSV reports), payment disputes, and payment sessions. Read-only by default; optional write tools allow capturing orders, issuing refunds, extending authorization times, cancelling orders, and releasing remaining authorization.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@klarna-mcp check order 3a1f9b2c-7d4e-4a8f-9c1e-2b5d6f8a0c3d, and any captures"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
|
| Order status, amounts (authorized, captured, refunded, remaining), expiry, lines, captures and refunds |
|
| All captures on an order |
|
| One capture |
|
| One refund (all refunds are listed on the order) |
|
| Payouts with totals, by date range and currency, paginated |
|
| One payout by the reference on your bank statement |
|
| Totals per currency for a date range |
|
| Settlement transactions by payout and/or order, paginated |
|
| One payout with its transactions, as CSV text |
|
| All payouts and transactions in a date range, as CSV text |
|
| Disputes by order, state, reason, reference and dates, cursor-paginated |
|
| One dispute with its requests and deadlines |
|
| A Klarna Payments session (never creates or updates one) |
Write tools (only with KLARNA_ENABLE_WRITES=true)
Tool | Klarna endpoint | Annotation |
|
| destructive |
|
| destructive |
|
| not destructive |
|
| destructive |
|
| 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
Read-only unless you say otherwise. Without
KLARNA_ENABLE_WRITES=true(exactlytrue) the write tools do not exist on the server, so the model cannot call them, whatever the prompt says.Playground first.
KLARNA_ENVdefaults toplayground. Point it atproductiononly after you have watched the tools behave on test orders.Idempotency on every write. Each write sends a
Klarna-Idempotency-Keyheader. 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 sameidempotency_keyand Klarna executes it at most once (Klarna keeps keys for 24 hours).Credentials stay out of the conversation. They are read from the environment and sent only in the
Authorizationheader. Error messages are built from Klarna'serror_code,error_messagesandcorrelation_id, and anything that looks like a credential is redacted before it reaches the model.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 buildThis gives you dist/stdio.js. Node 20 or newer is required.
3. Configure
Variable | Default | Meaning |
| API credential username | |
| API credential password (the API key or shared secret) | |
| Alternative to the two above: a | |
|
|
|
|
|
|
| off |
|
Region and environment map to Klarna's documented hosts:
Production | Playground | |
|
|
|
|
|
|
|
|
|
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.jsAdd -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_reference1on the order.Settlements dates are date-times. A bare date means midnight, so ask for
2026-09-30T23:59:59Zto 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.jsTests 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.jsSources
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 toolsget_captureGet captureBRead-onlyIdempotent
Get one capture on a Klarna order by capture_id (amounts in minor units).
Inputs: order_id (required), capture_id (required).
get_disputeGet disputeARead-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 orderARead-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 sessionARead-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 payoutARead-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)ARead-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)ARead-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 summaryARead-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 refundARead-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 capturesBRead-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 disputesARead-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 payoutsARead-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 transactionsARead-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
Scored across 13 tools
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.
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.
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.
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
Related MCP Connectors
Connect your ads, shop, analytics, social, CRM and finance platforms once, then let Claude, ChatGPT, Cursor or any MCP client read, join and explain your numbers. Public statistics from the World Bank, IMF, Eurostat, OECD, WHO and SEC filings come as context, searchable and chartable from the same tools. Read-only by design, every number carries its source.
Amazon Ads, Seller Central, Vendor Central and AMC data for AI agents. Read-only by default.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseAqualityCmaintenanceEnables 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.9MIT
- AlicenseBqualityCmaintenanceEnables 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.7MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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