# inpost-consumer-mcp

[![npm version](https://img.shields.io/npm/v/inpost-consumer-mcp)](https://www.npmjs.com/package/inpost-consumer-mcp)
[![License: MIT](https://img.shields.io/github/license/noxlabs-ai/inpost-consumer-mcp)](LICENSE)
[![Node.js](https://img.shields.io/node/v/inpost-consumer-mcp)](https://nodejs.org/)

**npm:** [inpost-consumer-mcp](https://www.npmjs.com/package/inpost-consumer-mcp) · **GitHub:** [noxlabs-ai/inpost-consumer-mcp](https://github.com/noxlabs-ai/inpost-consumer-mcp)

Local [MCP](https://modelcontextprotocol.io/) (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](https://noxlabsai.com/).

---

## Table of contents

- [Why this project](#why-this-project)
- [Features](#features)
- [Quick start](#quick-start)
- [Tools](#tools)
- [Configuration](#configuration)
- [Library](#library)
- [How it works](#how-it-works)
- [Development](#development)
- [Publishing](#publishing)
- [Disclaimer](#disclaimer)
- [License](#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](https://nodejs.org/) 20 or newer.

Published on npm as [`inpost-consumer-mcp`](https://www.npmjs.com/package/inpost-consumer-mcp) — see the [package page](https://www.npmjs.com/package/inpost-consumer-mcp) for the latest version.

### Connect your AI client

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

```json
{
  "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](#configuration)).

### Run manually (optional)

```bash
npx -y inpost-consumer-mcp
```

Or install globally:

```bash
npm install -g inpost-consumer-mcp
inpost-consumer-mcp
```

### Global install (optional)

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

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

### Local development

```json
{
  "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

```json
{
  "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

```ts
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

```mermaid
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

```bash
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](https://www.npmjs.com/package/inpost-consumer-mcp)

Repository: [https://github.com/noxlabs-ai/inpost-consumer-mcp](https://github.com/noxlabs-ai/inpost-consumer-mcp)

For maintainers releasing a new version:

```bash
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](LICENSE) © [NOXLABS](https://noxlabsai.com/)