io.github.elchin92/avito-mcp

Reports only token METADATA: present/absent, expiresInSec, last refresh error. The token itself is NEVER returned — for that use the auth_* tools under AVITO_MCP_EXPOSE_AUTH_TOOLS=1 (hidden by default). By default it does not force a refresh — if probe=true, it will attempt getToken() (which may trigger a refresh).

Cancels a previously deferred action. After cancellation the confirmation_id is no longer valid.

Returns a machine-readable description of the current configuration: mode, allow/deny lists, confirmation, dry-run, idempotency, local file access. Useful for an agent to understand which operations are fundamentally available before attempting to call tools.

⚠️ Executes a previously deferred action by its confirmation_id. Use ONLY after explicit human confirmation — the flow is designed as a server-side two-step guard against accidental one-shot execution, not as cryptographic protection against an autonomous agent. Confirmation is single-use: the id is deleted after a successful call. AVITO_MCP_CONFIRMATION_SECRET is not set — soft-confirmation is in effect. Set the env variable to switch to hard-confirmation.

Returns the most recently observed X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset values, grouped by logical API domain (core, messenger, items, etc.) across all processes in the current account namespace. Useful for diagnosing "why am I being throttled" — Avito enforces a per-minute limit.

Universal health-check: package version, active capabilities, rate-limit status, idempotency ledger size, pending actions count, dryRun default. Does not call the Avito API. Safe to call as often as you like.

Lists the current pending actions awaiting confirmation. Args are not shown — only tool name, risk, a brief summary, and the creation and expiration times. Use it to diagnose "what did I just ask to confirm".

[BETA] Checks whether a discount/special-offer messenger campaign is available for a list of listings (available). Read-only; sends nothing and charges nothing. For each itemId it returns isAvailable and, when not available, a reason. Run this FIRST, before msg_discounts_open_api_multi_create. Do not confuse it with ..._tariff_info (campaigns remaining in the plan) or ..._stats (statistics for sent campaigns).

[BETA] ⚠️ SECOND, final step: confirms and PAYS from the Avito wallet for the discount/special-offer campaign created via msg_discounts_open_api_multi_create (multi_confirm). IRREVERSIBLE and PUBLIC: messages are sent to recipients (buyers who added the listing to favorites) and money is deducted from the account; if funds are insufficient an error is returned. Always confirm the action with the user before calling. Unlike ..._available/..._tariff_info/..._stats (read-only), this method performs the actual send and charge.

[BETA] Creates a draft discount/special-offer messenger campaign for a list of listings and locks in the recipient audience (multi_create). This is the FIRST step — the campaign is NOT sent yet and no money is charged: it returns dispatches (id, created/notCreated status, recipient count) and the available offers with their price. Then pick an offer and confirm it via msg_discounts_open_api_multi_confirm — only then are the messages sent to recipients (public). Check listing eligibility in advance via ..._available.

[BETA] Returns statistics for already-sent discount/special-offer campaigns over a period (stats). Read-only; sends nothing and charges nothing. For each campaign: itemId, offerSlug, send and expiration dates, the number of offers sent (count) and accepted by buyers (accepted), the discount amount, and the cost. Use it to analyze results; for eligibility checks use ..._available, and for the remaining plan balance use ..._tariff_info.

[BETA] Returns information about the current discount/special-offer campaign plan: how many campaigns remain (sendsLeft) and the total allowance (totalSends) (tariff_info). Read-only, no parameters, sends nothing and charges nothing; if there is no active plan, the response is empty. Do not confuse it with ..._available (per-listing eligibility) or ..._stats (statistics for already-sent campaigns).

⚠️ Confirms the buyer's return of an item and selects the Russian Post office the return parcel will be sent to (accept_return_order). Write/public operation for courier delivery (Courier): the confirmation is visible to the buyer and irreversibly starts the return process. Call it when the order has an available acceptReturnOrder action. The response contains a success flag.

⚠️ Applies an order status transition (apply_transition), such as confirmation or cancellation. WARNING: the new status is visible to the buyer and affects the deal; the transition is irreversible. The allowed transitions depend on the current status — see the list of available actions in availableActions from orders_get_orders. The response contains a success flag.

Verifies the confirmation code for handing over an order at a pickup point (check_confirmation_code): the buyer states the code from the app and the method validates it. Effectively a read check, it does not change the order. The response contains status: success (code valid), fail (invalid), expired (expired), or attempts (attempts exhausted). Do not confuse it with delivery_check_confirmation_code from the delivery domain — this method belongs to order management.

⚠️ Prepares a click-and-collect order and sends the details to the buyer (cnc_set_details, CNC = click-and-collect). Write operation: the seller sets the pickup address, the booking period, and a comment the buyer will see. Call it when the order has an available setCNCDetails action. After handover, confirmation is done via orders_apply_transition (receive) with the buyer's code.

Downloads the generated PDF file with labels by taskID (download_label). Read-only, changes nothing. Call it AFTER orders_generate_labels or orders_generate_labels_extended, once the generation task is complete — the taskID comes from their response. Returns a structured binary response {mimeType: "application/pdf", sizeBytes, base64}; decode the base64 to save or print the file. If the task is not ready yet or the taskID is wrong, a 404 is returned.

Creates a task to generate PDF labels for orders (generate_labels, up to 100 orders at a time). Available only for pickup-point orders. Returns a taskID; wait for it to be ready and download the file via orders_download_label. For large batches (up to 1000 orders) use orders_generate_labels_extended — it has a higher limit but a strict rate limit (1 request/min).

Creates a task to generate PDF labels for a large batch of orders (generate_labels_extended, up to 1000 orders at a time). Available only for pickup-point orders. Difference from orders_generate_labels: a higher order limit (1000 vs 100), but a strict rate limit — 1 request per minute. Returns a taskID; wait for it to be ready and download the file via orders_download_label.

Returns the available time slots for a courier to pick up the item (get_courier_delivery_range), for seller-courier delivery (RDBS/Courier). Read-only. Call it BEFORE orders_set_courier_delivery_range — a specific slot is chosen from the response (dateOptions with intervals and intervalType). Do not confuse it with the set version: this one only reads the available intervals, it does not book them.

Returns a list of delivery orders (get_orders) with filters by ID, status, and creation date. Read-only, changes nothing. Use it as a starting point: take the available actions from the response (availableActions: confirm/reject/perform/receive/setMarkings/setTrackNumber/setCNCDetails, etc.) for subsequent write operations. Available only to B2C sellers. The response includes a hasMore flag for pagination.

⚠️ Submits "Chestny Znak" marking codes (DataMatrix) for the items in an order (markings). Write operation: stores the codes on the Avito side; required when the order has a setMarkings action (see availableActions in orders_get_orders). Maximum 50 marking records per request; the response contains an array of per-item results (success/error). Do not confuse it with status transitions (orders_apply_transition) — this method only attaches codes, it does not change the order status.

⚠️ Selects (books) a specific time slot for a courier to pick up the item (set_courier_delivery_range), for seller-courier delivery. A write operation, unlike the read method orders_get_courier_delivery_range, which only shows the available slots — call it first and take the interval and intervalType from the response. Can be called again to change the time while the courier has not yet picked up the parcel. The response contains a success flag.

⚠️ Submits the parcel tracking number for delivery by the seller's partners (set_tracking_number, DBS). Write/public operation: the tracking number is visible to the buyer for tracking. Call it when the order has an available setTrackNumber action (or fixTrackNumber to correct it). The response contains a success flag; on error, code: incorrect_number (invalid number) or already_set (the number is already attached to another order).

⚠️ PAID ACTION (money): creates a BBIP order to enable promotion for listings and CHARGES the budget from the account balance. The order is created only if there are no errors across all listings; if funds are insufficient — 402. FIRST estimate the cost and return for free: promotion_get_bbip_suggests_by_items_v1 (budget options) → promotion_get_bbip_forecasts_by_items_v1 (forecast). Then for each listing pass an option from suggests as {itemId, duration, oldPrice, price} (oldPrice/price — kopecks/day, duration — days; full budget = price × duration). Returns orderId (UUID) — check its status via promotion_get_order_status_v1.

Returns the forecast effect of BBIP promotion (listing promotion bid/budget): expected increase in views (min/max) and total cost for the period. READ-ONLY: spends NO money; use BEFORE promotion_create_bbip_order_for_items_v1 to estimate the return. For each listing pass {itemId, duration, oldPrice, price} — the same values as for create; take them from promotion_get_bbip_suggests_by_items_v1 (budgets[].{oldPrice,price} — kopecks/day, duration.recommended — days). Returns items[].{min,max,totalPrice} (kopecks) and an overall totalPrice.

Returns recommended BBIP promotion bid/budget options for the listings. READ-ONLY: spends NO money. This is the first step of the BBIP flow: from the response take items[].budgets[].{oldPrice,price} (kopecks/day, isRecommended flags the recommended one) and items[].duration.{from,to,recommended} (days), then pass them to promotion_get_bbip_forecasts_by_items_v1 (forecast) and promotion_create_bbip_order_for_items_v1 (paid purchase).

Returns a dictionary of all Avito promotion service types: for each service — slug (type identifier), name and isDeprecated (whether it is deprecated). READ-ONLY: spends NO money and requires no parameters. Use it as a reference to resolve slugs in the responses of other promotion methods.

Returns the status of a BBIP order by its orderId: the order's overall status (initialized/waiting/in_process/processed), totalPrice (kopecks) and a per-item status for each listing (slug, price, errorReason). READ-ONLY: spends NO money. Call it AFTER promotion_create_bbip_order_for_items_v1 to track the order's execution.

Returns active promotion services for the specified listings: for each listing, a list of services with slug, name and startDate/endDate dates. READ-ONLY: spends NO money. Use it to find out which promotion is already enabled and until what date it is active (not to be confused with suggests, which propose new budget options).

Returns a paginated list of the current user's promotion orders: id (UUID), createdAt and status of each order. READ-ONLY: spends NO money. Use it for order history/overview; the detailed status of a specific order is available via promotion_get_order_status_v1 by its orderId.

Publishes a seller answer to a review (reviews_create_review_answer_v1). WARNING: the answer is PUBLIC — once moderated it is visible to everyone on the profile page. Requires reviewId (from reviews_get_reviews_v1) and the message text; returns the id of the created answer and a timestamp. Confirm the action with the user. To delete an answer, use reviews_remove_review_answer_v1.

Returns the aggregated rating of the current user (reviews_get_ratings_info_v1): average score, the total number of active reviews and the number of reviews that affect the rating, plus a flag indicating whether the rating is enabled. Takes no parameters and returns no paginated data. To get the list of reviews itself, use reviews_get_reviews_v1.

Returns a paginated list of active reviews for the current user (reviews_get_reviews_v1): review id, score, text, author, listing, attached photos and the current seller answer, plus total — the overall number of reviews. Use it to browse individual reviews and obtain the reviewId (required for reviews_create_review_answer_v1). If you only need the aggregate score without the list, use reviews_get_ratings_info_v1.

Permanently deletes a previously published seller answer to a review (reviews_remove_review_answer_v1). WARNING: deletion is IRREVERSIBLE and immediately removes the public answer from the profile; returns a success flag. Confirm the action with the user. To publish an answer again, use reviews_create_review_answer_v1.

Reads current stock (available quantity) for a list of listings in the warehouse (get_stocks_info). Read-only, changes nothing. Returns for each item_id: quantity (available = submitted/edited minus reserved), is_unlimited, is_multiple, is_out_of_stock. To change stock, use stock_update_stocks.

⚠️ Updates the stock (quantity) of items across listings in the warehouse (update_stocks). Affects whether listings are available to order: quantity=0 marks a listing as "out of stock". Accepts an array of {item_id, quantity, external_id?}; quantity is an integer 0..999999. Returns success and errors for each listing. For current stock, use stock_get_stocks_info.

Returns the account tariff information for the Transport category (tariffs_get_tariff_info, read-only). The response includes the current and scheduled contracts — tariff level, activity status, start/end dates (Unix time), bonuses, prices with and without discount, and listing packages with their categories, locations, price groups, and remaining balance. Use it to check tariff terms and the remaining listing balance. Takes no parameters. Available only for tariffs in the "Transport" category and not for the "CPA" tariff; otherwise it returns 404.

⚠️ Applies transactional promo/promotion with a pay-per-result commission to listings (trxpromo_apply). Affects price/spend: the promotion fee is added on top of the base commission. The response includes a success flag per listing, and on error a code 1001 (validation) or 1002 (promo unavailable) along with the allowed commission range. First check the limits via trxpromo_get_commissions; cancel a running promo with trxpromo_cancel.

⚠️ Cancels active and scheduled transactional promo for listings (trxpromo_cancel). Reverts the effect of trxpromo_apply — the promotion and its associated commission stop applying. The response includes a success flag per listing, and on error a code 1001 (validation) or 1002 (promo unavailable). Apply promo again with trxpromo_apply; check commissions with trxpromo_get_commissions (read-only).

Checks transactional promo availability and the allowed commission range for listings (trxpromo_get_commissions, read-only — does not start anything or charge any fee). For each listing it returns the promoAvailable flag and settings: minimum/maximum/step of the commission in hundredths of a percent (100 = 1%). Use before trxpromo_apply to learn the commission limits. Start promo with trxpromo_apply, cancel with trxpromo_cancel. This is a GET with a request body — non-standard, but that is exactly how it is defined in the Avito swagger.

Reads the account wallet balance (get_user_balance): the amount of real money (real) and the amount of bonus funds (bonus) in rubles. Read-only, a point-in-time snapshot. This is the Personal Account wallet, not the CPA balance (for CPA see the cpa domain). For the history of charges/top-ups use post_operations_history.

Returns the profile of the currently authorized account (get_user_info_self): numeric id (this is the Profile_id), email, name, verified phone numbers, and profile_url. Read-only, no parameters. Handy for finding out the Profile_id and checking which account the server is running under; for the balance use get_user_balance, for the list of operations use post_operations_history.

Returns the list of account wallet operations for a period (post_operations_history): charges and top-ups in money and bonuses, with amountRub, amountBonus, amountTotal, operation type/name, service type (vas, cpa, tariff, etc.), itemId, and dates for each operation. Read-only. These are Personal Account wallet movements, not the CPA balance. Constraints: dateTimeFrom no more than a year ago, the range between from/to no more than one week; for the current balance use get_user_balance.