How do I use alopeyk-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@alopeyk-mcp قیمت ارسال بسته از تهران به شیراز چقدر است؟" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

alopeyk-mcp

by dwin-gharibi

Overview Schema Source Related Servers Discussions Admin

Python

Remote

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

Docker

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:

Service	Base URL	Auth	Tool prefix
On-Demand	`https://api.alopeyk.com/api/v2/` (sandbox: `https://sandbox-api.alopeyk.com/api/v2/`)	`Authorization: Bearer <access_token>` (pre-issued JWT)	`alopeyk_`
Alonomic (الونومیک)	`https://api.alopeyk.com/business-service/api/v1/`	email/password → token (cached, re-login on 401), or pre-issued `alonomic_token`	`alonomic_`

🔐 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:

environments

Related MCP server: royalmail-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:

order-lifecycle

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)

Variable	Default	Description
`ALOPEYK_ENVIRONMENT`	`production`	`production` or `sandbox` (selects default base/tracking URLs).
`ALOPEYK_ACCESS_TOKEN`	—	On-Demand JWT (`Authorization: Bearer`).
`ALOPEYK_EMAIL`	—	Alonomic login email (with `ALOPEYK_PASSWORD`).
`ALOPEYK_PASSWORD`	—	Alonomic login password.
`ALOPEYK_ALONOMIC_TOKEN`	—	Pre-issued Alonomic token (wins over email/password).
`ALOPEYK_ENABLE_ORDERING`	`false`	Allow creating/modifying real deliveries/parcels.
`ALOPEYK_READ_ONLY`	`false`	Master switch: forces ordering off.
`ALOPEYK_ONDEMAND_BASE_URL`	derived	Override the On-Demand base URL.
`ALOPEYK_BUSINESS_BASE_URL`	derived	Override the Alonomic base URL.
`ALOPEYK_TRACKING_URL`	derived	Override the tracking web-app base URL.
`ALOPEYK_VERIFY_SSL`	`true`	Verify TLS certificates.
`ALOPEYK_TIMEOUT`	`30`	Per-request timeout (seconds).
`ALOPEYK_DEFAULT_INSTANCE`	`default`	Instance used when `instance` is omitted.
`ALOPEYK_LOG_LEVEL`	`INFO`	`DEBUG` / `INFO` / `WARNING` / ...

Nested (named instances)

Variable	Description
`ALOPEYK__INSTANCES__<NAME>__ENVIRONMENT`	`production` / `sandbox` for `<NAME>`.
`ALOPEYK__INSTANCES__<NAME>__ACCESS_TOKEN`	On-Demand JWT for `<NAME>`.
`ALOPEYK__INSTANCES__<NAME>__EMAIL`	Alonomic login email for `<NAME>`.
`ALOPEYK__INSTANCES__<NAME>__PASSWORD`	Alonomic login password for `<NAME>`.
`ALOPEYK__INSTANCES__<NAME>__ALONOMIC_TOKEN`	Pre-issued Alonomic token for `<NAME>`.
`ALOPEYK__INSTANCES__<NAME>__ENABLE_ORDERING`	Ordering switch for `<NAME>`.
`ALOPEYK__INSTANCES__<NAME>__READ_ONLY`	Master switch (forces ordering off) for `<NAME>`.
`ALOPEYK__INSTANCES__<NAME>__ONDEMAND_BASE_URL`	On-Demand base for `<NAME>`.
`ALOPEYK__INSTANCES__<NAME>__BUSINESS_BASE_URL`	Alonomic base for `<NAME>`.
`ALOPEYK__INSTANCES__<NAME>__TRACKING_URL`	Tracking base for `<NAME>`.
`ALOPEYK__INSTANCES__<NAME>__VERIFY_SSL`	TLS verification (default `true`).
`ALOPEYK__INSTANCES__<NAME>__TIMEOUT`	Per-request timeout seconds (default `30`).
`ALOPEYK__DEFAULT_INSTANCE`	Instance used when `instance` is omitted.
`ALOPEYK__LOG_LEVEL`	`DEBUG` / `INFO` / `WARNING` / ...

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

Flag	Default	Gates	Effective when
`enable_ordering`	`false`	`alopeyk_create_order`, `alopeyk_cancel_order`, `alopeyk_finish_order`, `alopeyk_loyalty_products(buy=true)`, `alonomic_create_parcel`, `alonomic_update_parcel`, `alonomic_cancel_parcel`	`enable_ordering=true` and `read_only=false`
`read_only`	`false`	forces `enable_ordering` off	—

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:

safety-gates

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

Tool	Method · Endpoint	Notes
`alopeyk_get_address(lat, lng)`	`GET locations?latlng=<lat>,<lng>`	reverse geocode
`alopeyk_location_suggestion(input, latlng?)`	`GET locations?input=&location=`	autocomplete
`alopeyk_get_price(transport_type, addresses, has_return?, cashed?, optimize?)`	`POST orders/price/calc`	read-only quote
`alopeyk_get_batch_price(orders)`	`POST orders/batch-price`	≤15 orders
`alopeyk_create_order(transport_type, addresses, has_return?, cashed?, scheduled_at?, discount_coupon?)`	`POST orders`	⚠️ `enable_ordering`
`alopeyk_get_order(order_id)`	`GET orders/{id}?columns=...`	read-only
`alopeyk_cancel_order(order_id, comment)`	`GET orders/{id}/cancel?comment=`	⚠️ `enable_ordering`
`alopeyk_finish_order(order_id, comment?, rate?)`	`POST orders/{id}/finish`	⚠️ `enable_ordering`
`alopeyk_get_config()`	`GET config`	read-only
`alopeyk_get_profile()`	`GET show-profile?columns=*,credit`	read-only
`alopeyk_validate_coupon(code)`	`POST coupons`	read-only
`alopeyk_loyalty_products(product_id?, buy?)`	`GET\|POST loyalty/customer/products/{id?}`	buy ⚠️ `enable_ordering`
`alopeyk_tracking_url(order_token)`	local `<tracking>#/<token>`	no network
`alopeyk_print_invoice_url(order_id, order_token)`	local	no network
`alopeyk_payment_route(user_id, amount, gateway=saman)`	local (saman\|zarinpal)	no network
`alopeyk_transport_types()`	local	motorbike, motor_taxi, cargo, cargo_s, car
`alopeyk_cities()`	local	tehran, shemiranat, rey, karaj, isfahan, tabriz, mashhad, shiraz

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

Tool	Method · Endpoint	Notes
`alonomic_login()`	`POST login`	caches token (never returns it)
`alonomic_get_me()`	`GET me`	read-only
`alonomic_get_days()`	`GET days`	read-only
`alonomic_get_days_index()`	`GET days/index`	7 days, each `{same, next}`
`alonomic_create_parcel(drop, parcel, pickup, delivery_proofs?, parcel_extra_params?)`	`POST parcels`	⚠️ `enable_ordering`
`alonomic_get_parcel(parcel_id)`	`GET parcels/{id}`	read-only
`alonomic_update_parcel(parcel_id, ...)`	`PUT parcels/{id}`	⚠️ `enable_ordering`
`alonomic_cancel_parcel(parcel_id)`	`DELETE parcels/{id}`	⚠️ `enable_ordering` (204)
`alonomic_calc_parcel(drop, parcel, pickup?)`	`POST parcels/calc`	read-only estimate
`alonomic_get_parcel_sizes()`	`GET parcels/size`	12 box sizes
`alonomic_get_saved_addresses()`	`GET pickup-saved-addresses`	read-only
`alonomic_add_saved_address(title, lat, lng, address, ...)`	`POST pickup-saved-addresses`	address book
`alonomic_delete_saved_address(address_id)`	`DELETE pickup-saved-addresses/{id}`	address book (204)
`alonomic_parcel_statuses()`	local	static status → Persian label map

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/).

architecture

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

self-hosting

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

request-flow

The full tool surface, grouped by service: The order lifecycle and the Alonomic parcel flow: 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.

Available Tools

34 tools

alonomic_add_saved_addressA

Save a new pickup address.

Persian purpose: افزودن یک آدرس پیکاپ جدید. Maps to POST /business-service/api/v1/pickup-saved-addresses. This manages your address book (not a delivery), so it is NOT gated by enable_ordering.

Args: title: A label for the saved address. lat: Latitude (-90..90). lng: Longitude (-180..180). address: Free-text street address. person_name: Optional contact name at the address. person_phone: Optional contact phone. plate_number: Optional building plate number. unit_number: Optional unit number. postal_code: Optional postal code. instance: Configured instance to use (default when omitted).

Inputs: title (required), lat (required), lng (required), address (required), +6 more. Returns: object

alonomic_calc_parcelA

Estimate a parcel's price and dimensions (read-only).

Persian purpose: محاسبه هزینه و ابعاد یک مرسوله. Does NOT create a parcel. Maps to POST /business-service/api/v1/parcels/calc. The response includes id, length, width, height, worth.

Args: drop: Drop-off, {address: {province, city}} (route end). parcel: {size, value, weight, is_packaging_required?, is_label_required?}. pickup: Optional {date_type, date, address: {province, city}}. instance: Configured instance to use (default when omitted).

Inputs: drop (required), parcel (required), pickup, instance. Returns: object

alonomic_cancel_parcelA

Cancel a parcel before pickup — WARNING: changes a real parcel.

Persian purpose: لغو یک مرسوله پیش از جمع‌آوری. Requires Alonomic credentials AND enable_ordering=true (and read_only=false); otherwise it returns {"error": "ordering_disabled", ...} without contacting the API. Maps to DELETE /business-service/api/v1/parcels/{id} (HTTP 204 on success).

Args: parcel_id: Numeric id of the parcel to cancel. instance: Configured instance to use (default when omitted).

Inputs: parcel_id (required), instance. Returns: object

alonomic_create_parcelA

Create a REAL business parcel — WARNING: this is billable.

Persian purpose: ثبت یک مرسوله واقعی. Requires Alonomic credentials AND enable_ordering=true (and read_only=false); otherwise it returns {"error": "ordering_disabled", ...} without contacting the API. Maps to POST /business-service/api/v1/parcels.

Args: drop: Drop-off, {address: {province, city, lat, lng, address, person_name, person_phone, plate_number, unit_number, postal_code, description}}. parcel: Parcel details, {size:int, barcode?, invoice?, value:int, weight:int, is_packaging_required:0/1, is_label_required:0/1}. pickup: Pickup, {date, date_type:"same"|"next", address: {lat, lng, address, person_name, person_phone, postal_code}}. delivery_proofs: Optional {code, image, signature}. parcel_extra_params: Optional {custom_field_1, custom_field_2}. instance: Configured instance to use (default when omitted).

Inputs: drop (required), parcel (required), pickup (required), delivery_proofs, +2 more. Returns: object

alonomic_delete_saved_addressA

Delete a saved pickup address.

Persian purpose: حذف یک آدرس پیکاپ ذخیره‌شده. Maps to DELETE /business-service/api/v1/pickup-saved-addresses/{id} (HTTP 204 on success). Manages the address book, so it is NOT gated by enable_ordering.

Args: address_id: Numeric id of the saved address to delete. instance: Configured instance to use (default when omitted).

Inputs: address_id (required), instance. Returns: object

alonomic_get_daysA

Get today/tomorrow working pickup days (read-only).

Persian purpose: دریافت روزهای کاری امروز و فردا. Maps to GET /business-service/api/v1/days.

Args: instance: Configured instance to use (default when omitted).

Inputs: instance. Returns: object

alonomic_get_days_indexA

Get the next 7 days with same/next-day availability (read-only).

Persian purpose: تقویم ۷ روز آینده با امکان ارسال همان‌روز/روز بعد. Maps to GET /business-service/api/v1/days/index. Each day is shaped like {same: bool, next: bool}.

Args: instance: Configured instance to use (default when omitted).

Inputs: instance. Returns: object

alonomic_get_meA

Get the Alonomic business account profile and credit (read-only).

Persian purpose: دریافت اطلاعات حساب کاربری الونومیک. Logs in implicitly if needed. Maps to GET /business-service/api/v1/me. Returns {id, name, phone_number, email, credit, final_credit}.

Args: instance: Configured instance to use (default when omitted).

Inputs: instance. Returns: object

alonomic_get_parcelA

Get one business parcel by id (read-only).

Persian purpose: دریافت مشخصات یک مرسوله. Maps to GET /business-service/api/v1/parcels/{id}.

Args: parcel_id: Numeric id of the parcel. instance: Configured instance to use (default when omitted).

Inputs: parcel_id (required), instance. Returns: object

alonomic_get_parcel_sizesB

List the standard parcel box sizes (read-only).

Persian purpose: فهرست اندازه‌های استاندارد جعبه. Maps to GET /business-service/api/v1/parcels/size (12 box sizes with dimensions).

Args: instance: Configured instance to use (default when omitted).

Inputs: instance. Returns: object

alonomic_get_saved_addressesB

List saved pickup addresses (read-only).

Persian purpose: فهرست آدرس‌های پیکاپ ذخیره‌شده. Maps to GET /business-service/api/v1/pickup-saved-addresses.

Args: instance: Configured instance to use (default when omitted).

Inputs: instance. Returns: object

alonomic_loginA

Persian purpose: ورود به سرویس الونومیک و کش‌کردن توکن. Runs the email/password login (POST /business-service/api/v1/login) and caches the returned token in memory for subsequent Alonomic calls. If the instance is configured with a pre-issued alonomic_token instead, it simply reports success. The token value is NEVER returned.

Args: instance: Configured instance to log in (default when omitted).

Returns: {authenticated: true, instance, method} on success, where method is "alonomic_token" or "login"; otherwise a structured error.

Inputs: instance. Returns: object

alonomic_parcel_statusesA

List Alonomic parcel status codes and Persian labels (static).

Persian purpose: فهرست وضعیت‌های مرسوله و معنای فارسی آن‌ها. Returns a static map of status code -> Persian label. No request is sent.

Args: instance: Accepted for symmetry; ignored (static data).

Inputs: instance. Returns: object

alonomic_update_parcelA

Update a parcel before final send — WARNING: changes a real parcel.

Persian purpose: ویرایش یک مرسوله پیش از ارسال نهایی. Requires Alonomic credentials AND enable_ordering=true (and read_only=false); otherwise it returns {"error": "ordering_disabled", ...} without contacting the API. Maps to PUT /business-service/api/v1/parcels/{id}. Only fields you pass are sent.

Args: parcel_id: Numeric id of the parcel to update. drop: Optional updated drop-off object. parcel: Optional updated parcel details object. pickup: Optional updated pickup object. delivery_proofs: Optional updated {code, image, signature}. parcel_extra_params: Optional {custom_field_1, custom_field_2}. instance: Configured instance to use (default when omitted).

Inputs: parcel_id (required), drop, parcel, pickup, +3 more. Returns: object

alopeyk_cancel_orderA

Cancel an order — WARNING: this changes a real delivery.

Persian purpose: لغو یک سفارش. On-Demand, requires an access_token AND enable_ordering=true (and read_only=false); otherwise it returns {"error": "ordering_disabled", ...} without contacting the API. Maps to GET /api/v2/orders/{id}/cancel?comment=<c>.

Args: order_id: Numeric id of the order to cancel. comment: Reason / note for the cancellation (required by Alopeyk). instance: Configured instance to use (default when omitted).

Inputs: order_id (required), comment (required), instance. Returns: object

alopeyk_citiesA

List the cities served by Alopeyk On-Demand (static, no network).

Persian purpose: فهرست شهرهای تحت پوشش. Returns the static list of supported city slugs. No request is sent.

Args: instance: Accepted for symmetry; ignored (static data).

Inputs: instance. Returns: object

alopeyk_create_orderA

Create a REAL delivery order — WARNING: this is billable.

Persian purpose: ثبت یک سفارش واقعی. On-Demand, requires an access_token AND enable_ordering=true (and read_only=false) on the instance; otherwise it returns {"error": "ordering_disabled", ...} without contacting the API. Maps to POST /api/v2/orders.

Dispatches a courier and charges the account. Confirm the addresses, transport type, and price (via alopeyk_get_price) before calling.

Args: transport_type: Vehicle class (motorbike, motor_taxi, cargo, cargo_s, car). addresses: Ordered stops, each {type, lat, lng} — one origin and one or more destinations. has_return: Whether the courier returns to origin (default false). cashed: Whether the delivery is cash-on-delivery (default false). scheduled_at: Optional ISO timestamp to schedule the pickup. discount_coupon: Optional discount coupon code to apply. instance: Configured instance to use (default when omitted).

Inputs: transport_type (required), addresses (required), has_return, cashed, +3 more. Returns: object

alopeyk_docsA

Return offline documentation about both Alopeyk services and the tools.

Persian purpose: راهنمای آفلاین الوپیک و ابزارها. Use this to learn what Alopeyk offers across its On-Demand and Alonomic services and how each tool maps to the underlying API, without making any network call. Links point to https://docs.alopeyk.com.

Args: topic: Optional tool name (e.g. alopeyk_get_price or alonomic_create_parcel) to fetch docs for a single tool. When omitted, returns the service overview plus the full tool list.

Returns: A dict with service metadata and matching tool documentation.

Inputs: topic. Returns: object

alopeyk_finish_orderA

Finish/close an order, optionally rating it — WARNING: real delivery.

Persian purpose: اتمام و امتیازدهی به یک سفارش. On-Demand, requires an access_token AND enable_ordering=true (and read_only=false); otherwise it returns {"error": "ordering_disabled", ...} without contacting the API. Maps to POST /api/v2/orders/{id}/finish with body {comment, rate}.

Args: order_id: Numeric id of the order to finish. comment: Optional free-text comment about the delivery. rate: Optional courier rating (typically 1-5). instance: Configured instance to use (default when omitted).

Inputs: order_id (required), comment, rate, instance. Returns: object

alopeyk_get_addressA

Reverse-geocode a coordinate to a human-readable address.

Persian purpose: تبدیل مختصات جغرافیایی به آدرس. On-Demand, requires an access_token. Maps to GET /api/v2/locations?latlng=<lat>,<lng>.

Args: lat: Latitude (-90..90). lng: Longitude (-180..180). instance: Configured instance to use (default when omitted).

Inputs: lat (required), lng (required), instance. Returns: object

alopeyk_get_batch_priceA

Calculate prices for up to 15 orders in one call (read-only).

Persian purpose: محاسبه قیمت گروهی چند سفارش. On-Demand, requires an access_token. This does NOT create orders. Maps to POST /api/v2/orders/batch-price.

Args: orders: A list (max 15) of order objects, each shaped like the body of alopeyk_get_price (transport_type + addresses + flags). instance: Configured instance to use (default when omitted).

Inputs: orders (required), instance. Returns: object

alopeyk_get_configA

Get the On-Demand service configuration (read-only).

Persian purpose: دریافت تنظیمات سرویس آن‌دیمند. Requires an access_token. Maps to GET /api/v2/config. Returns service-wide settings (pricing params, supported types, limits, ...).

Args: instance: Configured instance to use (default when omitted).

Inputs: instance. Returns: object

alopeyk_get_orderA

Get one order with rich columns (status, courier, ETA) — read-only.

Persian purpose: مشخصات کامل یک سفارش. On-Demand, requires an access_token. Maps to GET /api/v2/orders/{id} with a rich columns set (addresses, progress, courier_info, eta_minimal, ...).

Args: order_id: Numeric id of the order to fetch. instance: Configured instance to use (default when omitted).

Inputs: order_id (required), instance. Returns: object

alopeyk_get_priceA

Calculate the price for a delivery between stops (read-only).

Persian purpose: محاسبه قیمت یک سفارش. On-Demand, requires an access_token. This does NOT create an order. Maps to POST /api/v2/orders/price/calc. The response includes status, price, credit, distance, duration, user_credit, and price_with_return.

Args: transport_type: Vehicle class (e.g. motorbike, motor_taxi, cargo, cargo_s, car). See alopeyk_transport_types. addresses: Ordered stops, each {type, lat, lng} — one type="origin" followed by one or more type="destination". has_return: Whether the courier returns to the origin (default false). cashed: Whether the delivery is cash-on-delivery (default false). optimize: Whether to optimize the multi-stop route (default false). instance: Configured instance to use (default when omitted).

Inputs: transport_type (required), addresses (required), has_return, cashed, +2 more. Returns: object

alopeyk_get_profileA

Get the authenticated user's profile and wallet credit (read-only).

Persian purpose: دریافت پروفایل و اعتبار کاربر. Requires an access_token. Maps to GET /api/v2/show-profile?columns=*,credit.

Args: instance: Configured instance to use (default when omitted).

Inputs: instance. Returns: object

alopeyk_location_suggestionA

Autocomplete address suggestions for a free-text query.

Persian purpose: پیشنهاد آدرس بر اساس متن جست‌وجو. On-Demand, requires an access_token. Maps to GET /api/v2/locations?input=<query>&location=<latlng?>.

Args: input: The partial address / place name to search for. latlng: Optional "lat,lng" bias to rank nearby results first. instance: Configured instance to use (default when omitted).

Inputs: input (required), latlng, instance. Returns: object

alopeyk_loyalty_productsA

List loyalty products, or buy one — buying is gated by enable_ordering.

Persian purpose: مشاهده محصولات وفاداری یا خرید یک محصول. Requires an access_token. Listing (buy=false) maps to GET /api/v2/loyalty/customer/products/{id?}. Buying (buy=true) maps to POST /api/v2/loyalty/customer/products/{id} and spends loyalty points/credit — it requires enable_ordering=true (and read_only=false), otherwise it returns {"error": "ordering_disabled", ...} without contacting the API.

Args: product_id: Optional loyalty product id (required when buy=true). buy: When true, purchase the product (a real, gated action). instance: Configured instance to use (default when omitted).

Inputs: product_id, buy, instance. Returns: object

alopeyk_payment_routeA

Build a wallet top-up payment route URL (no network call).

Persian purpose: ساخت مسیر پرداخت برای شارژ کیف پول. Returns a payment URL on the On-Demand host for the chosen gateway. No request is sent.

Args: user_id: Numeric id of the user to credit. amount: Amount to top up (in the account's currency unit). gateway: Payment gateway, saman or zarinpal (default saman). instance: Configured instance whose On-Demand base URL to use.

Inputs: user_id (required), amount (required), gateway, instance. Returns: object

alopeyk_print_invoice_urlA

Build the printable invoice URL for an order (no network call).

Persian purpose: ساخت لینک چاپ فاکتور سفارش. Returns a URL on the On-Demand host for printing the order's invoice. No request is sent.

Args: order_id: Numeric id of the order. order_token: The order's token. instance: Configured instance whose On-Demand base URL to use.

Inputs: order_id (required), order_token (required), instance. Returns: object

alopeyk_tracking_urlA

Build the public tracking URL for an order token (no network call).

Persian purpose: ساخت لینک رهگیری سفارش. Returns <tracking>#/<token> where the tracking base comes from the instance's environment (production vs sandbox). No request is sent.

Args: order_token: The order's tracking token (from a created order). instance: Configured instance whose tracking base URL to use.

Inputs: order_token (required), instance. Returns: object

alopeyk_transport_typesA

List the available transport (vehicle) types (static, no network).

Persian purpose: فهرست انواع وسیله نقلیه. Returns the known transport types used by the pricing/order tools. No request is sent.

Args: instance: Accepted for symmetry; ignored (static data).

Inputs: instance. Returns: object

alopeyk_validate_couponA

Validate a discount coupon code (read-only).

Persian purpose: بررسی اعتبار کد تخفیف. Requires an access_token. Maps to POST /api/v2/coupons with body {code}.

Args: code: The coupon code to validate. instance: Configured instance to use (default when omitted).

Inputs: code (required), instance. Returns: object

healthcheckA

Check that Alopeyk is reachable via a lightweight On-Demand call.

Persian purpose: بررسی در دسترس بودن الوپیک. Calls the On-Demand GET /api/v2/config endpoint and reports whether the API responded. Requires an access_token (config is an authenticated endpoint). Returns {reachable: true} on success or a structured error otherwise.

Args: instance: Name of the configured Alopeyk instance. Defaults to the configured default instance when omitted.

Inputs: instance. Returns: object

list_instancesA

List the configured Alopeyk instances (no secrets).

Persian purpose: فهرست نمونه‌های پیکربندی‌شده. Useful for discovering which instance values the other tools accept, which environment each targets, and which credentials/flags are set. Credential values (access_token, email, password, alonomic_token) are NEVER returned — only booleans saying whether they are configured.

Returns: {default_instance, instances: [{name, environment, ondemand_base_url, business_base_url, tracking_url, has_ondemand_credentials, has_alonomic_credentials, alonomic_auth_method, enable_ordering, read_only, ordering_allowed, verify_ssl}]}.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored 2026-06-21 05:25 across 34 tools

Disambiguation5/5

Tools are clearly separated by prefix (alopeyk_ vs alonomic_) and each has a distinct purpose. Even within groups, tools like alopeyk_get_price and alopeyk_get_batch_price are well-differentiated. Overlap is minimal.

Naming Consistency4/5

The majority follow a verb_noun pattern with consistent prefixes. However, a few tools (healthcheck, list_instances, alopeyk_payment_route, alopeyk_print_invoice_url) break the pattern, causing minor inconsistency.

Tool Count4/5

34 tools is on the higher side but reasonable for a server covering two distinct service APIs with full CRUD and utility operations. Each tool earns its place without unnecessary duplication.

Completeness3/5

The tool set covers core operations for both Alopeyk and Alonomic services, but lacks listing tools for orders and parcels. Agents cannot retrieve a list of existing orders or parcels, which is a notable gap.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Furgonetka.pl - Logistics & Shipping MCP Server
pl.furgonetka.api
Furgonetka MCP Server is an extension for LLMs (such as Claude) that integrates AI assistants with Poland's most popular courier brokerage platform. The server enables models to interact directly with services from various couriers (including InPost, DPD, DHL, UPS, and Poczta Polska) through a single, unified interface. With this integration, your AI stops just "writing about logistics" and starts actually managing it.
E-commerce & Retail Monitoring Travel & Transportation
2
https://api.furgonetka.pl/mcp
TokenOracle
com.guffeyholdings
Hosted MCP server for LLM cost estimation, model comparison, and budget-aware routing.
Finance Monitoring
2
https://mcp.guffeyholdings.com/TokenOracle
Relm CRMA
com.relmcrm
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
CRM AI & Machine Learning
412
https://api.relmcrm.com/mcp
geo
co.thinair
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
Location Services Weather Services Travel & Transportation
2
https://geo.thinair.co/mcp

Related MCP Servers

Agent Toolbox
Search Web Scraping Weather Services
Vincentwei1021
A
license
Not graded
quality
D
maintenance
Production-ready MCP server for AI agents — web search, content extraction, screenshots, weather, finance, email validation, translation, and IP geolocation.
Updated 8 months ago (2026-03-10 13:06 UTC)
3 npm
6
MIT
royalmail-mcp
E-commerce & Retail Travel & Transportation
catrinmdonnelly
A
license
A
quality
C
maintenance
Connect any MCP-compatible AI to Royal Mail shipping. This server exposes five tools that let Claude, Cursor or any MCP client book orders, fetch postage labels, track shipments and cancel bookings through the official Click & Drop API.
Updated a day ago (2026-11-10 19:02 UTC)
5
19 npm
3
MIT
shipsaving-mcp
E-commerce & Retail
waka4674
A
license
B
quality
D
maintenance
An MCP server that wraps the ShipSaving logistics REST API, enabling AI assistants like Claude to perform shipping operations through natural language.
Updated 7 months ago (2026-04-21 02:19 UTC)
30
48 npm
MIT
mcp-logistics-tracker
Travel & Transportation Search
k3-yamada
A
license
A
quality
D
maintenance
MCP server for tracking Japanese logistics carriers (Yamato, Sagawa, Japan Post) via mock or AfterShip adapter. Enables AI agents to query shipment status and history in natural language.
Updated 4 months ago (2026-07-08 14:03 UTC)
3
MIT

Tool	Description
`healthcheck`	Calls the On-Demand `config` endpoint and reports reachability.
`list_instances`	Lists configured instances (environment, base URLs, which creds set, `enable_ordering`, `read_only`, `ordering_allowed`) — never credential values.
`alopeyk_docs(topic?)`	Offline reference for both services + links to https://docs.alopeyk.com.

Two services in one server

🔐 Required header

⚠️ Ordering safety

Install

Quick start

Configuration (multi-account / multi-instance)

Shorthand (single default instance)

Nested (named instances)

Control flags & safety

Authentication

Use with an MCP client

Tools

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

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

Meta

Prompts

Skill

Architecture

Self-hosting & scaling

Testing

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Agent Toolbox

royalmail-mcp

shipsaving-mcp

mcp-logistics-tracker

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

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