baselinker-mcp

An MCP server that puts the whole BaseLinker API — orders, invoices, returns, couriers, CRM, warehouses, products — in front of an LLM client such as Claude Code, Claude Desktop or Cursor.

• Complete. All 179 documented API methods, none of them stubbed.

• Read-only until you say otherwise. The 92 write methods stay invisible unless you opt in; with writes off, every tool reports readOnlyHint: true.

• Local or remote. stdio for a client on your machine, or Streamable HTTP with OAuth 2.1 (Keycloak) for a shared endpoint on the internet.

"How many orders came in yesterday that aren't paid yet?"
"Which catalog products dropped below 5 in stock this week?"
"Pull the courier label for order 1234567 and tell me the tracking number."

Contents

• Quickstart

• Connecting a client

• Tools

• Write methods

• Behaviour worth knowing

• Remote deployment (HTTP + OAuth)

• Configuration reference

• Troubleshooting

• Development

Related MCP server: TextQL MCP Server

Quickstart

Requirements: Node.js 20 or newer, and a BaseLinker API token from the BaseLinker panel under Account & other → My account → API.

git clone https://github.com/PiotrRaszkowski/baselinker-mcp.git
cd baselinker-mcp
npm install
npm run build
cp .env.example .env     # paste your token into BASELINKER_API_TOKEN

The token can also come straight from the environment, which takes precedence over .env. .env is read from the package root, so the server starts correctly no matter which directory your MCP client launches it from.

Connecting a client

Claude Code

claude mcp add baselinker -e BASELINKER_API_TOKEN=your-token -- node /path/to/baselinker-mcp/dist/index.js

Claude Desktop, Cursor, or any mcpServers config

{
  "mcpServers": {
    "baselinker": {
      "command": "node",
      "args": ["/path/to/baselinker-mcp/dist/index.js"],
      "env": { "BASELINKER_API_TOKEN": "your-token" }
    }
  }
}

For a shared endpoint reachable from claude.ai, see Remote deployment.

Tools

179 separate tools would swamp a model's context and its ability to choose between them, so methods are grouped the way BaseLinker itself groups them: ten tools, one per API category. Each takes a method name and a parameters object, and each tool's description lists the methods it accepts along with their parameters and pagination hints.

Counts below are read + write; write methods only appear when BASELINKER_ALLOW_WRITES=true.

Parameters are validated against a Zod schema per method before anything is sent, so a malformed call comes back as a readable error instead of a BaseLinker error code. Unknown keys are forwarded untouched — BaseLinker adds parameters without warning, and the server does not break when it does.

Write methods

Disabled by default. To enable:

BASELINKER_ALLOW_WRITES=true

While disabled, write methods are neither listed in any tool's method enum nor callable. Enabling turns on all 92 at once — creating, updating and deleting orders, products, stock, prices, invoices, shipments, returns and warehouse documents. Some of them delete records; some dispatch real courier shipments that cost real money. There is no per-method gating, so enable writes only for a client you trust, and consider running a second read-only instance for everything else.

Behaviour worth knowing

Rate limiting. BaseLinker allows 100 requests per minute. A client-side sliding-window limiter enforces it — excess calls wait their turn rather than failing.

Pagination. List responses are capped (typically 100 items for orders, invoices and returns; 1000 for catalog products). Each method's description carries the specific hint, for example getOrders wants date_confirmed_from set to the last returned order's date_confirmed plus one second, while getInventoryProductsList takes a 1-based page.

File downloads. getLabel, getProtocol, getCourierDocument, getInvoiceFile, getInventoryDocumentFile and getInventoryFulfillmentDeliveryLabels return the file as an MCP embedded resource with a real MIME type. Pass the extra save_to_path parameter — handled locally, never sent to BaseLinker — to decode it to disk instead and get back { saved_to, extension, bytes }. This only makes sense over stdio, where the server runs on your own machine; over HTTP it is rejected with an explanatory error.

Remote deployment (HTTP + OAuth)

With --transport http the server speaks Streamable HTTP and acts as an OAuth 2.0 Resource Server (RFC 9728): it publishes protected resource metadata, answers unauthenticated calls with 401 plus a WWW-Authenticate challenge, and verifies every access token as an RS256 JWT against a Keycloak realm's JWKS. Clients discover the realm from that metadata and register themselves through Dynamic Client Registration, so no client ID or secret is configured on either side.

node dist/index.js --transport http --host 0.0.0.0 --port 8000 --path /mcp

HTTP transport refuses to start without an auth realm unless you opt out explicitly with BASELINKER_MCP_AUTH_DISABLED=true. That is deliberate: with writes enabled, an unauthenticated endpoint hands the internet your BaseLinker account.

deploy/ has the full guide — Keycloak realm setup, a hardened Compose service with Traefik labels, reverse-proxy snippets for Caddy and nginx, verification commands and a threat model. The short version:

docker build -t baselinker-mcp:0.2.0 .
docker run -d --name baselinker-mcp -p 8000:8000 \
  -e BASELINKER_API_TOKEN=your-token \
  -e BASELINKER_MCP_AUTH_REALM_URL=https://keycloak.example.com/realms/myrealm \
  -e BASELINKER_MCP_AUTH_BASE_URL=https://mcp.example.com \
  baselinker-mcp:0.2.0

Then point a client at it:

claude mcp add --transport http baselinker https://mcp.example.com/mcp

In claude.ai it is Settings → Connectors → Add custom connector, URL https://mcp.example.com/mcp, with Client ID and Client Secret left empty.

One thing to be clear about before you expose it: the BaseLinker token is shared. Everyone who can log into the realm operates on the same BaseLinker account. See SECURITY.md for the rest of the boundaries.

Configuration reference

Everything is an environment variable; .env in the package root is loaded automatically.

Always

Transport

CLI flags win over these.

OAuth — required when transport is http

Lists accept commas or spaces.

Troubleshooting

More OAuth-specific cases are in deploy/README.md.

Development

npm run dev         # run from sources (tsx), stdio transport
npm run start:http  # built server, HTTP transport
npm test            # unit tests — fully offline, no live API calls
npm run check       # format check + typecheck + tests, what CI runs
npm run smoke       # manual smoke test against the live API (uses .env)
npm run inspect     # MCP Inspector against the built server

CONTRIBUTING.md covers how the tool registry is put together and what to watch out for when adding a method.

License

MIT. Not affiliated with or endorsed by BaseLinker.