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.

Powered by NOXLABS.

Table of contents

• Why this project

• Features

• Quick start

• Tools

• Configuration

• Library

• How it works

• Development

• Publishing

• Disclaimer

• License

Related MCP server: MCP API Server

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

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.

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

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 © NOXLABS