User Guide

End-to-end walkthrough — from the moment you download the zip to the moment Claude is reading live data out of your Linnworks account. Allow 20–30 minutes for a first-time deploy if you've used Cloudflare Workers before, an hour if you haven't.

1. Prerequisites

Before you start, line these up:

• Cloudflare account — free plan is fine. Sign up at dash.cloudflare.com/sign-up if you haven't already.
• Linnworks Premium or Multichannel subscription — the API isn't available on lower tiers.
• Node 18+ installed locally. Check with node --version.
• Wrangler CLI — Cloudflare's deploy tool. Comes in as a dev dependency when you npm install, but you can install it globally if you prefer: npm install -g wrangler.
• Basic comfort with TypeScript, Cloudflare Workers, and a terminal. You don't need to be an expert, but you should be unfazed by editing a config file and running npx wrangler deploy.
• An MCP-capable client — Claude Desktop is the easiest. Cursor, Windsurf, Cline, and others all work too.

2. Unpacking the download

After purchase, you'll get a download link in your purchase confirmation email and at app.mcp-g.com/app/downloads. Grab the zip and unpack it somewhere sensible.

unzip linnworks-mcp-v1.zip -d linnworks-mcp
cd linnworks-mcp

What's inside:

• src/ — the Worker source. src/index.ts is the entry point. src/linnworks/ holds the API client. src/mcp/ holds the MCP server implementation.
• package.json — dependencies and scripts. Run npm install to fetch them.
• tsconfig.json — TypeScript config. You shouldn't need to touch this.
• wrangler.toml — Cloudflare Workers config. You will need to edit this (Worker name, Durable Object bindings).
• README.md — a condensed version of this guide. Refer to it when you're offline.

3. Registering your Linnworks application

Linnworks treats every connector as an "application". You need to register one so you have an Application ID and Application Secret to authenticate with.

1. Go to developer.linnworks.net and sign in with your Linnworks credentials.
2. Click Applications → New Application.
3. Give it a name like "My Linnworks MCP". The name is only visible to you.
4. Linnworks requires a Callback URL field. The connector doesn't run a callback route — Linnworks just redirects your browser here once after install so you can copy the install token out of the URL bar. A safe placeholder is https://your-worker-name.your-subdomain.workers.dev/health (a real, harmless endpoint the connector ships). You can leave it like that forever — you only land on this URL once, at install time.
5. Select the read scopes you want exposed to Claude — at minimum: Orders Read, Stock Read, Processed Orders Read, Purchase Orders Read, Returns Read.
6. Save. Copy the Application ID and Application Secret to a password manager — you'll paste them as Worker secrets in step 5.

4. First deploy to Cloudflare

From the unpacked folder:

npm install
npx wrangler login
# (opens a browser, sign in to your Cloudflare account)

Open wrangler.toml and set a Worker name that's unique to your account:

name = "linnworks-mcp-acme"
main = "src/index.ts"
compatibility_date = "2025-01-15"

[[durable_objects.bindings]]
name = "SESSIONS"
class_name = "SessionStore"

[[migrations]]
tag = "v1"
new_classes = ["SessionStore"]

Now deploy:

npx wrangler deploy

Wrangler will print your deployed Worker URL. It looks like https://linnworks-mcp-acme.your-subdomain.workers.dev. Note this down — you'll need it twice more in this guide.

If this first deploy fails, jump to Troubleshooting — the most common cause is not being logged in.

5. Setting Worker secrets (part 1 of 2)

The Worker reads four secrets at runtime. Three you can set now — the fourth (LINNWORKS_INSTALL_TOKEN) comes from the Linnworks install in step 6. Set the first three with wrangler secret put:

npx wrangler secret put LINNWORKS_APPLICATION_ID
# paste the Application ID from step 3, hit Enter

npx wrangler secret put LINNWORKS_APPLICATION_SECRET
# paste the Application Secret from step 3, hit Enter

npx wrangler secret put MCP_BEARER_TOKEN
# paste any long random string — this is your auth token for Claude → Worker
# generate one with: openssl rand -hex 32

The bearer token is what Claude will send in the Authorization header on every request to your Worker. Anyone with this token can read your Linnworks data, so treat it like a password.

After all three are set, re-deploy so the Worker picks them up:

npx wrangler deploy

6. Installing into your Linnworks account & capturing the install token

Right now Linnworks knows your application exists, but your actual Linnworks account hasn't authorised it — and the Worker has no install token to authenticate with. Both happen in one flow.

1. Open Linnworks and go to Settings → Apps.
2. Click Install and choose Install Custom App.
3. Paste your Application ID from step 3.
4. Linnworks shows you the read permissions your app requests. Approve them.
5. Linnworks then redirects your browser to the Callback URL you set in step 3 — with the install token appended as a query parameter. Your address bar will look something like:

   https://your-worker-name.your-subdomain.workers.dev/health?token=abc123def456...&applicationId=...

   Do not navigate away. The token is shown once — there's no "show me again" link in Linnworks.
6. Copy the value after ?token= and before the next &. This is your install token.
7. Back in your terminal, set it as the fourth Worker secret:

   npx wrangler secret put LINNWORKS_INSTALL_TOKEN
   # paste the install token, hit Enter

8. Re-deploy so the Worker can authenticate:

   npx wrangler deploy

9. Confirm the Worker can reach Linnworks by curling its health endpoint and then a real MCP call:

   curl https://your-worker-name.your-subdomain.workers.dev/health
   # → {"ok":true,"service":"linnworks-mcp",...}

Once LINNWORKS_INSTALL_TOKEN is set and the Worker is re-deployed, the connector will exchange those credentials for a Linnworks session token on its first call and cache the session in KV for 30 minutes. It re-auths automatically when the session expires or 401s.

7. Connecting Claude Desktop

Now wire Claude up to your Worker.

1. Open Claude Desktop.
2. Go to Settings → Developer → Edit Config. This opens claude_desktop_config.json in your editor.
3. Add a server entry:

{
  "mcpServers": {
    "linnworks": {
      "url": "https://linnworks-mcp-acme.your-subdomain.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_BEARER_TOKEN_HERE"
      }
    }
  }
}

Replace the URL with your actual Worker URL and the bearer token with the one you set in step 5. Save the file and fully quit and re-open Claude Desktop — it only picks up MCP server changes on restart.

If Claude Desktop shows the server as Connected with a green dot, you're done with setup. Cursor, Windsurf, Cline and others use a similar JSON config — the URL and Authorization header are what matter.

8. Verifying it works

Open a new chat in Claude and ask something only your Linnworks data could answer:

You should see Claude call the get_stock_levels tool, wait a second or two, and come back with a real answer drawn from your Linnworks inventory. Try a few more:

• "How many orders did we ship last week?"
• "What's our open purchase order value right now?"
• "Show me the last five returns and their reasons."
• "Which customer has spent the most with us in the last 90 days?"

If Claude says it can't access your data or the tools aren't visible, work through Troubleshooting — 90% of issues are one of: bearer token mismatch, app not installed in Linnworks, or wrong/missing LINNWORKS_INSTALL_TOKEN secret.

9. Updating the connector when we release a new version

We ship updates roughly every 4–6 weeks — bug fixes, new tools, perf improvements, Linnworks API changes. Updates are free for 12 months from purchase.

To update:

1. Sign in at app.mcp-g.com/app/downloads and re-download the latest zip.
2. Unzip it next to your existing folder — e.g. linnworks-mcp-v2.
3. Copy your existing wrangler.toml over the new one (it has your Worker name and bindings). The new release notes will flag if any new bindings or migrations are required.
4. Run npm install in the new folder.
5. Run npx wrangler deploy. The Worker updates in place — secrets, KV-cached sessions, and your Linnworks install stay intact.
6. Restart Claude Desktop so it re-fetches the tool list (some updates add or rename tools).

You do not need to re-register the Linnworks application or re-install it in your Linnworks account on updates — it's the same App ID and the same Worker URL.

10. Deploying for multiple Linnworks clients (agencies & dev shops)

If you're an agency, freelance Linnworks consultant, or in-house team running multiple Linnworks accounts, the connector deploys cleanly one-per-client. The licence covers unlimited end-clients of the purchaser — you don't need to buy a separate copy per account.

Architecture: one Worker per Linnworks account

Linnworks's app authorisation is account-scoped — each install produces its own install token, tied to one Linnworks account. The cleanest deployment model is therefore one Cloudflare Worker per client, each with its own four secrets. This gives you:

• Per-client isolation. A misbehaving client (runaway loop, leaked bearer token, app uninstall) only affects their Worker. The blast radius stays small.
• Per-client bearer token rotation. Each client gets a different MCP_BEARER_TOKEN. If one leaks, you rotate that one — the others are untouched.
• Per-client billing visibility. Cloudflare's per-Worker analytics let you see exactly which client is generating which usage. Helpful if you bill on consumption.
• Easier offboarding. Drop a client → npx wrangler delete linnworks-mcp-acme and it's gone in seconds.

Naming convention

We recommend linnworks-mcp-{client-slug} — e.g. linnworks-mcp-acme, linnworks-mcp-northcliff, linnworks-mcp-bakers-emporium. This makes the deployed URLs self-describing in your Cloudflare dashboard, in wrangler tail output, and in the Claude Desktop config you hand the client. Keep slugs lowercase, hyphenated, and stable — they end up in the URL the client sees.

Per-client deploy workflow

1. Make a copy of the unpacked source folder per client, or maintain a single source tree and override wrangler.toml's name field via the --name flag at deploy time.
2. For each client, run through steps 3–6 above using their Linnworks account: register the app inside their developer.linnworks.net (the client owns the Application ID and Secret), set the four Worker secrets against the client's Worker name, install into the client's Linnworks account and capture the install token.
3. Give the client the Worker URL and a per-client bearer token. They paste both into their Claude Desktop config. They never see your other clients' deployments.

Billing pattern that works

The most common pattern we see from agencies who've bought the source is a flat monthly fee per client — typically £20–£60/month, depending on what tier of support you're offering — covering Worker hosting, updates (you re-deploy when we ship a new version), and break-fix support. Cloudflare's free Workers plan covers most clients comfortably (100,000 requests/day), so your costs scale per-client only if a client really hammers it.

One Application per client, not one shared Application

The buyer of the source code owns the source — your clients each own their own Linnworks Application registration. That's the right boundary.