alopeyk-mcp

A self-hostable Model Context Protocol server for Alopeyk (الوپیک) — an Iranian on-demand delivery & logistics company.

Unofficial integration. This is a community-built MCP server. The "Alopeyk" and "Alonomic" names and logos belong to their owner. Not affiliated with, endorsed by, or sponsored by Alopeyk. Creating real deliveries/parcels incurs real charges — use the order tools at your own risk.

alopeyk-mcp exposes Alopeyk's APIs as MCP tools and prompts so an LLM agent (Claude, etc.) can geocode addresses, quote and track deliveries, manage business parcels, and — when you explicitly allow it — create and cancel real deliveries/parcels. It is a small, stateless, async Python process you run yourself.

It mirrors the structure and quality of the sibling ramzinex-mcp / roshan-* servers: typed httpx client, pydantic-settings configuration, full test suite, Docker / Helm / Kubernetes / Terraform deploy assets, and generated architecture diagrams.

Two services in one server

Alopeyk runs two distinct API services, and this server wraps both behind one process, routing each call to the right base automatically:

🔐 Required header

Every call to both services carries:

X-Requested-With: XMLHttpRequest
Content-Type: application/json; charset=utf-8

The server adds these automatically.

⚠️ Ordering safety

Creating, updating, cancelling, or finishing real deliveries/parcels (and buying loyalty products) is gated by a single per-instance flag, default false:

• enable_ordering gates alopeyk_create_order, alopeyk_cancel_order, alopeyk_finish_order, alopeyk_loyalty_products(buy=true), alonomic_create_parcel, alonomic_update_parcel, and alonomic_cancel_parcel.

A master read_only flag forces ordering off regardless of its value. When the gate is off the tool returns a structured refusal and never calls the API:

{"error": "ordering_disabled", "message": "Set enable_ordering=true (and read_only=false) to create/modify real deliveries/parcels."}

Read-only tools (geocoding, pricing, viewing orders/parcels, days, sizes, address book) are always allowed. The access token, the Alonomic login token, and the password are never logged and are redacted from every error message.

Production vs. sandbox — selected per instance by environment:

Related MCP server: pumperly-mcp

Install

pip install -e .            # from a checkout
# or, for development:
pip install -e ".[dev]"

Requires Python 3.11+.

Quick start

The offline/static tools (docs, transport types, cities, URL helpers, parcel statuses) work with zero configuration:

python -m alopeyk_mcp          # stdio transport (default)

To use On-Demand tools, provide the pre-issued JWT; to use Alonomic tools, provide an email + password (or a pre-issued alonomic_token):

export ALOPEYK_ENVIRONMENT=production              # or sandbox
# On-Demand (/api/v2/):
export ALOPEYK_ACCESS_TOKEN=your-ondemand-jwt
# Alonomic (/business-service/): email + password login (cached, re-login on 401)
export ALOPEYK_EMAIL=ops@example.com
export ALOPEYK_PASSWORD=your-password
# ...or a pre-issued Alonomic token instead:
# export ALOPEYK_ALONOMIC_TOKEN=your-alonomic-token

# Opt in to the gated mutation tools (default false):
export ALOPEYK_ENABLE_ORDERING=true                # allow create/cancel/finish + parcels
python -m alopeyk_mcp

Run over HTTP for networked clients:

python -m alopeyk_mcp --transport streamable-http --host 0.0.0.0 --port 8000

Order lifecycle — creating/cancelling is gated by enable_ordering:

Configuration (multi-account / multi-instance)

Configuration is read from environment variables via pydantic-settings. One process can front many Alopeyk accounts/environments — each is a named instance with its own credentials and safety policy. Every API tool accepts an optional instance argument; omit it to use the default.

Shorthand (single default instance)

Nested (named instances)

Example: a production business account, a sandbox account, and a strictly read-only viewer.

ALOPEYK__INSTANCES__BIZ__ENVIRONMENT=production
ALOPEYK__INSTANCES__BIZ__ACCESS_TOKEN=prod-ondemand-jwt
ALOPEYK__INSTANCES__BIZ__EMAIL=ops@example.com
ALOPEYK__INSTANCES__BIZ__PASSWORD=secret
ALOPEYK__INSTANCES__BIZ__ENABLE_ORDERING=true
ALOPEYK__INSTANCES__SANDBOX__ENVIRONMENT=sandbox
ALOPEYK__INSTANCES__SANDBOX__ACCESS_TOKEN=sandbox-jwt
ALOPEYK__INSTANCES__SANDBOX__ENABLE_ORDERING=true
ALOPEYK__INSTANCES__READONLY__ACCESS_TOKEN=viewer-jwt
ALOPEYK__INSTANCES__READONLY__READ_ONLY=true
ALOPEYK__DEFAULT_INSTANCE=biz

See .env.example for a complete, annotated file. Use list_instances to see what's configured (names, environment, base URLs, has_ondemand_credentials, has_alonomic_credentials, alonomic_auth_method, enable_ordering, read_only, ordering_allowed) — it never reveals credential values.

Control flags & safety

When the gate is off, the tool returns {"error": "ordering_disabled", "message": ...} and never contacts the API.

Authentication

• On-Demand — a pre-issued access_token (JWT), sent as Authorization: Bearer <token>. Required for all alopeyk_* network tools.

• Alonomic — either a pre-issued alonomic_token, or email + password which the server POSTs to login, caching the returned token in memory per instance, reusing it, and re-authenticating once on a 401. Call alonomic_login to trigger/verify the login explicitly (it never returns the token).

The access token, the Alonomic token, and the password are never logged or echoed (Authorization / access_token / alonomic_token / token / password are all redacted from errors).

The read_only master switch overrides the enable_ordering gate:

Use with an MCP client

Add it to your client's MCP server config (stdio):

{
  "mcpServers": {
    "alopeyk": {
      "command": "python",
      "args": ["-m", "alopeyk_mcp"],
      "env": {
        "ALOPEYK_ENVIRONMENT": "production",
        "ALOPEYK_ACCESS_TOKEN": "your-ondemand-jwt",
        "ALOPEYK_EMAIL": "ops@example.com",
        "ALOPEYK_PASSWORD": "your-password",
        "ALOPEYK_ENABLE_ORDERING": "false"
      }
    }
  }
}

Tools

All 34 tools (17 On-Demand alopeyk_* + 14 Alonomic alonomic_* + 3 meta) accept an optional instance except the two purely-local meta tools (list_instances, alopeyk_docs).

On-Demand (alopeyk_) — /api/v2/, JWT Bearer

Alonomic (alonomic_) — /business-service/api/v1/, email/password login

Meta

⚠️ = creates/modifies a real delivery/parcel; gated by enable_ordering (forced off by read_only).

All 34 tools at a glance, grouped by service:

Prompts

The server also ships MCP prompts — safety-aware workflows your client can list and run (details in prompts/README.md):

• quote_delivery — geocode origin/destination, then quote with alopeyk_get_price.

• create_delivery_safely — a careful checklist that verifies enable_ordering, confirms addresses/type/price, then creates the order.

• track_order — alopeyk_get_order + alopeyk_tracking_url.

• alonomic_send_parcel — login → days/index → calc → create the parcel safely.

• address_book — review Alonomic saved addresses + parcel box sizes.

Skill

A ready-to-use Claude/agent skill lives at skills/alopeyk/SKILL.md. It describes when and how to use these tools across both services — quoting/tracking, the safe delivery flow, and the Alonomic parcel flow — with example tool sequences.

Architecture

The MCP client talks to one alopeyk-mcp process, which routes alopeyk_* calls to the On-Demand API (/api/v2/) and alonomic_* calls to the Alonomic business API (/business-service/api/v1/).

One process can serve many accounts/environments; the instance argument selects which credentials / ordering policy to use.

A typical On-Demand flow: suggest/geocode an address, quote the price, check the enable_ordering gate, then create and track the order.

The full tool surface, grouped by service: The order lifecycle and the Alonomic parcel flow:

The read_only master switch over enable_ordering, and the two environments: Regenerate the diagrams with make diagrams (uses the diagrams package + Graphviz dot and cairosvg).

Self-hosting & scaling

alopeyk-mcp is stateless, so you can run as many replicas as you like behind a load balancer. One process fronts multiple accounts via ALOPEYK__INSTANCES__<NAME>__* — no code change. Back off on HTTP 429 if Alopeyk rate-limits you. See deploy/ for Docker Compose, Kubernetes (raw + Kustomize), a Helm chart, and a Terraform module.

Testing

make smoke          # no-network smoke test (tools + prompts + descriptions)
make test           # full pytest suite (offline; all HTTP incl. Alonomic login mocked with respx)
make lint           # ruff

Live tests against the real API are skipped unless ALOPEYK_LIVE=1 is set (and the relevant credentials provided):

ALOPEYK_LIVE=1 ALOPEYK_ACCESS_TOKEN=... pytest tests/live -q

License

MIT. alopeyk-mcp is an unofficial, community-built integration; the Alopeyk and Alonomic names and logos belong to their owner.