inpost-consumer-mcp

npm: inpost-consumer-mcp · GitHub: noxlabs-ai/inpost-consumer-mcp

Local MCP (Model Context Protocol) server and TypeScript client for the InPost mobile / consumer API — SMS login, list parcels, pickup codes, open a Paczkomat, returns, and tracking.

Works with Cursor, Claude Desktop, VS Code (MCP-enabled clients), and any host that supports MCP over stdio.

---

Table of contents

• Why this project
• Features
• Quick start
• Tools
• Configuration
• Library
• How it works
• Development
• Publishing
• Disclaimer
• License

---

Why this project

InPost’s consumer mobile API powers “my parcels”, locker open, and returns — but it is not a polished public SDK. This package wraps that surface as:

1. An MCP server so AI assistants can list parcels, track shipments, and (with care) open a locker.
2. A typed TypeScript client you can import in your own scripts.

Auth is SMS OTP → JWT + refresh token, stored in a local multi-account config file and refreshed automatically.

Sign-in: call inpost_consumer_login. If a saved session exists, it refreshes tokens (no SMS). Otherwise it opens a localhost page for phone + SMS code. Secrets never go through the model. Pass forceSms=true to add another phone. If the MCP client supports URL elicitation, it will prompt you to open that page; otherwise the system browser is used.

---

Features

Feature	Description
9 MCP tools	Login (SMS), sessions, parcels, locker open/finish, track, returns
Multi-account	Several phone numbers in one local config (v2 store)
Auto token refresh	Proactive expiry check + one 401 retry (not exposed as a tool)
ShipX tracking	Public tracking via ShipX, with status cross-check on parcel lists
Typed client	Import InPostConsumerClient from the same package
stdio MCP	Drop-in for Cursor / Claude Desktop / VS Code

---

Quick start

Requirements: Node.js 20 or newer.

Published on npm as inpost-consumer-mcp — see the package page for the latest version.

Connect your AI client

Add this server entry to your MCP host’s configuration:

{
  "mcpServers": {
    "inpost-consumer": {
      "command": "npx",
      "args": ["-y", "inpost-consumer-mcp"]
    }
  }
}

Save the config, enable the inpost-consumer server if your client exposes a toggle, then sign in with inpost_consumer_login (refreshes a saved session, or opens browser OTP if needed).

No InPost developer keys. The server uses stdio transport only. Sessions are stored on disk (see Configuration).

Run manually (optional)

npx -y inpost-consumer-mcp

Or install globally:

npm install -g inpost-consumer-mcp
inpost-consumer-mcp

Global install (optional)

If you ran npm install -g inpost-consumer-mcp:

{
  "mcpServers": {
    "inpost-consumer": {
      "command": "inpost-consumer-mcp"
    }
  }
}

Local development

{
  "mcpServers": {
    "inpost-consumer": {
      "command": "node",
      "args": ["/absolute/path/to/inpost-consumer-mcp/dist/cli.js"]
    }
  }
}

Build first: npm install && npm run build.

Environment variables in MCP config

{
  "mcpServers": {
    "inpost-consumer": {
      "command": "npx",
      "args": ["-y", "inpost-consumer-mcp"],
      "env": {
        "INPOST_CONSUMER_CONFIG": "/custom/path/config.json"
      }
    }
  }
}

---

Tools

Auth uses the current mobile endpoints: POST /v1/account (send OTP) and POST /v1/account/verification (confirm). Parcels use GET /v4/parcels/tracked.

Tool	When to use
inpost_consumer_login	Refresh saved session, or browser SMS if needed (forceSms to add a phone)
inpost_consumer_logout	Sign out one or all phones
inpost_consumer_login_sessions	Show signed-in phones / expiry
inpost_consumer_list_parcels	List your parcels
inpost_consumer_get_parcel	Parcel details / pickup code
inpost_consumer_locker_open	Open Paczkomat (confirm=true)
inpost_consumer_locker_finish	End a pickup session
inpost_consumer_track	Track a shipment (ShipX)
inpost_consumer_list_returns	List return tickets

Safety: inpost_consumer_locker_open is destructive — anyone at the machine can take the parcel. Only call it when you are physically at the correct Paczkomat, and always pass confirm=true.

---

Configuration

Variable	Default	Description
INPOST_CONSUMER_CONFIG	OS app-config dir inpost-consumer-mcp/config.json	Path to the local auth/config JSON
INPOST_CONSUMER_BASE_URL	mobile API default	Override mobile API base URL
INPOST_SHIPX_BASE_URL	ShipX default	Override ShipX tracking base URL

---

Library

import { InPostConsumerClient } from "inpost-consumer-mcp";

const client = new InPostConsumerClient();
await client.sendSmsCode("+48123456789");
await client.confirmSmsCode("+48123456789", "123456");
const parcels = await client.listParcels({ statuses: ["ready_to_pickup"] });

Also exported: createMcpServer, ConfigStore, JWT helpers, status helpers, startLoginUi, openBrowser, and TOOL_NAMES.

The library still exposes sendSmsCode / confirmSmsCode for programmatic use. The MCP server uses a localhost browser UI instead so OTP codes never enter the chat.

---

How it works

flowchart LR
  Client[MCP client] -->|stdio| Server[inpost-consumer-mcp]
  Server --> Store[Local config store]
  Server --> Mobile[InPost mobile API]
  Server --> ShipX[ShipX tracking]
  Store --> JWT[JWT + refresh]

1. The MCP host starts inpost-consumer-mcp as a subprocess.
2. inpost_consumer_login refreshes a saved session when possible; otherwise opens a localhost page for SMS OTP and writes tokens to the local config file.
3. Parcel / locker / returns tools call the mobile API with auto-refreshed JWTs.
4. Tracking uses ShipX; parcel lists can cross-check public status.

---

Development

git clone https://github.com/noxlabs-ai/inpost-consumer-mcp.git
cd inpost-consumer-mcp
npm install
npm run gen        # optional: types from openapi/inpost-mobile.yml
npm run typecheck
npm run build
npm run smoke
npm run pack:check # dry-run npm pack

OpenAPI under openapi/inpost-mobile.yml describes the mobile endpoints used by this client.

Project layout

src/
  cli.ts                 # MCP stdio entrypoint (bin)
  index.ts               # Library exports
  auth/                  # Config store, JWT helpers, login UI, types
  client/                # HTTP + InPostConsumerClient
  mcp/                   # Server, tools, env config
  generated/             # Types from OpenAPI
openapi/
  inpost-mobile.yml
scripts/
  gen-types.mjs
  smoke.mts

Contributing

Contributions are welcome. Please:

1. Open an issue for larger changes.
2. Keep PRs focused; match existing TypeScript style.
3. Run npm run typecheck && npm run build before submitting.

---

Publishing

Package: https://www.npmjs.com/package/inpost-consumer-mcp

Repository: https://github.com/noxlabs-ai/inpost-consumer-mcp

For maintainers releasing a new version:

npm login
npm run pack:check
npm version patch   # or minor / major
npm publish

prepublishOnly runs typecheck and the build automatically.

---

Disclaimer

• This project is not affiliated with InPost Sp. z o.o. or InPost Group.
• It uses unofficial mobile API patterns that may change without notice.
• Opening a locker remotely can allow anyone nearby to take the parcel — use that tool only when you are at the machine.
• Use at your own risk; respect InPost terms of use and applicable law.

---

License

MIT © inpost-consumer-mcp contributors