io.github.elchin92/avito-mcp

[SANDBOX] Sets the working schedule of a delivery zone for a specific day that differs from the regular schedule (for example, holidays/weekends). Re-uploading overwrites the previous schedule for those dates. For delivery-service partners only. The body is an array of schedules directly (no wrapper).

[SANDBOX] Returns the sorting centers (hubs) for the specified delivery services. For delivery-service partners only. Delivery-service codes: pochta (Russian Post), exmail, bb (Boxberry), pp (PickPoint), dpd, and others.

[SANDBOX] Returns the status of an asynchronous task by the taskID obtained from upload operations (sorting centers, tags, areas, terms, tariff). Statuses: processing | success | <error>. Processing usually takes 5–20 minutes. For delivery-service partners only.

[SANDBOX] Prohibits the delivery service from accepting a parcel from the sender — the parcel will not be taken into processing. A step in the parcel-cancellation flow (pair with delivery_sandbox_cancel_parcel). Returns a success status. Implemented on the delivery-service side, for delivery-service PARTNERS only (a regular seller account gets 403/404).

[SANDBOX] Cancels a test parcel on behalf of the receiver (actor=receiver); returns a success status. Only parcels created via delivery_create_sandbox_parcel_v2 can be cancelled. Implemented on the delivery-service side, for delivery-service PARTNERS only. Unlike delivery_v1_cancel_parcel ([SANDBOX v1] with an options field), this is the base contract with an actor field.

[SANDBOX] Creates an announcement of a planned shipment to Avito in the test environment; after creation the announcement is routed to the delivery service specified in receiver. For delivery-service partners only. Unlike delivery_create_announcement_3pl (production /createAnnouncement), this is a sandbox, with no consequences.

[SANDBOX] Appends one tracking event for an announcement from the delivery service; does not modify existing history — use it to simulate an announcement progressing (ACCEPTANCE_DONE → RECEIVED → DELIVERED, or CANCELLED). One call records one event (not idempotent — re-sending logs a duplicate). Returns an empty 200 on success. For delivery-service PARTNERS only. This is the announcement-level analogue of delivery_tracking (which reports parcel-level status events).

[SANDBOX] Sets a parcel's delivery parameters on Avito — e.g. the final delivery cost. Idempotent by overwrite: each call REPLACES the previous values, so always send the complete current set, not a delta. Returns an empty 200 on success. For delivery-service PARTNERS only (not regular sellers). Sibling tools: delivery_set_order_real_address sets the pickup address, delivery_tracking pushes a status event — this one only sets cost/parameters.

[SANDBOX] Sends Avito the ACTUAL pickup point used for a parcel's acceptance/return — needed for agent and customer returns. Returns an empty 200 on success. Sibling: delivery_set_order_properties sets cost/parameters; this one only sets the address. For delivery-service PARTNERS only (not regular sellers).

[SANDBOX] Appends one parcel tracking event to Avito on behalf of the delivery service; does not modify existing history — a single status transition (e.g. RECEIVED_AT_TRANSIT_TERMINAL → IN_TRANSIT). Use this to report movement as it happens; one call records one event, and events accumulate into the parcel history (not idempotent — re-sending logs a duplicate). Returns an empty 200 on success; a 4xx means the order/status pair was rejected. Comply with Avito's retry policy on 5xx. For delivery-service PARTNERS only (not regular sellers). Sibling tools: delivery_set_order_properties sets cost/parameters, delivery_change_parcels reschedules a parcel — this one only appends a status event.

[SANDBOX] Creates a task to update the delivery-term zones in a tariff; returns a taskID — status via delivery_get_task. Important: the list of new terms must fully match the tariff's deliveryProviderZoneId values. For delivery-service partners only. The body is an array of zones directly.

[SANDBOX v1] Starts the process of cancelling a test announcement; on success the response has a success status. Available only in the Sandbox, for delivery-service partners. Unlike delivery_cancel_announcement_3pl (production /cancelAnnouncement), this is the test v1 contract with a required options field.

[SANDBOX v1] Cancels a test parcel: initiates an acceptance prohibition at the delivery service and, if it took effect, cancels the parcel. Only parcels created via delivery_create_sandbox_parcel_v2 can be cancelled. Available only in the Sandbox. Unlike delivery_sandbox_cancel_parcel (actor field), this is the v1 contract with an options field.

[SANDBOX v1] Creates a request to change ONE test parcel's data (e.g. the receiver's name/phone), per the type enum (changeReceiver / prohibitParcelReceive / extendParcelStorage / prohibitParcelAcceptance). The call only QUEUES the request — poll delivery_v1_get_change_parcel_info for the outcome. For bulk changes use delivery_change_parcels instead. Sandbox-only, for delivery-service PARTNERS.

[SANDBOX v1] Creates a test shipment announcement in the Sandbox (no real-world effect); returns a success status. Use the base contract delivery_sandbox_create_announcement unless you specifically need this v1 shape — the only difference is that v1 additionally requires the options field. Sandbox-only, for delivery-service PARTNERS.

[SANDBOX v1] Returns the last registered event for a test announcement — makes it easier to debug announcement-tracking integration. Available only in the Sandbox, for delivery-service partners.

[SANDBOX v1] Returns information about a test-parcel change request by its applicationID (the request is created via delivery_v1_change_parcel). Available only in the Sandbox, for delivery-service partners.

[SANDBOX v1] Returns information about a test parcel by parcelID. Available only in the Sandbox; works only with parcels created via delivery_create_sandbox_parcel_v2.

[SANDBOX v1] Returns the parcelID of a registered test parcel by its orderID. Works only with parcels created via delivery_create_sandbox_parcel_v2. Available only in the Sandbox.

Checks the status of the current user within the account hierarchy (check_ah_user). Returns the flags isCompany, isChief, isEmployee and avitoCompanyId — whether it is a company, a chief, an employee, and which company it is linked to. Read-only. Call before hierarchy_link_items_v1 to make sure the user belongs to a hierarchy and has the required role.

Returns the list of account-hierarchy employees of the managing company (get_employees). For each employee it returns employeeId, name, email, phones and the chief flag (isChief). Read-only. Requires an active account-hierarchy plan; the employeeId returned here is used in hierarchy_link_items_v1 and hierarchy_list_items_by_employee_id_v1.

Assigns listings to an employee within the account hierarchy (link_items). Changes the ownership of listings inside the managing account: a repeated call reassigns them to a different employee. Irreversible operation (the previous assignment is not restored automatically); on success returns HTTP 204 with no body. Requires hierarchy permissions (the account-hierarchy plan); the user state can be checked via hierarchy_check_ah_user_v1, and the employeeId can be taken from hierarchy_get_employees_v1.

Returns the list of phone numbers of the managing company in the account hierarchy (list_company_phones) with cursor-based pagination. The response contains a phones array and a cursor for the next page (if no cursor is returned, the list has ended). Read-only. Requires an active account-hierarchy plan.

Returns the IDs of listings assigned to a specific hierarchy employee, filtered by category (list_items_by_employee). The response contains an items array and a hasNext flag for cursor-based pagination. Fetching listings for the company as a whole is not available — only per employee. Read-only. Requires hierarchy permissions; employeeId is taken from hierarchy_get_employees_v1.

Applies ONE OR MORE promotion services (slugs) and/or stickers to a published listing (apply_vas, v2 — the current method). ⚠️ MONEY: charges money; irreversible. The response contains the IDs of the purchase operations for status tracking. The preferred replacement for the deprecated items_put_item_vas (a single service) and items_put_item_vas_package_v2 (a package). Within one request each service is applied only once; stickers are available only with the "XL listing" service, no more than three. First check the available slugs/stickers and price via items_post_vas_prices, and confirm with the user.

Returns detailed information about a SINGLE listing (get_item_info) — status, price, address, list of applied VAS services, etc. Read-only. Use it when the item_id is already known; for a list of listings, use items_get_items_info, and for view/contact statistics, use items_post_item_stats_shallow (this method does not return statistics). Limit: 500 requests/min.

Returns a LIST of the authenticated user's listings (get_items_info) — id, status, category, link on the site. Read-only, changes nothing. Use it to find listing ids and get an overview; for details on a single listing, use items_get_item_info. Supports pagination (page + per_page) and filters (status, category, updatedAtFrom). Limit: 25 requests/min. Does not work with employees' listings — for those (under the main account or as an authenticated employee) it returns an empty list.

Returns a REPORT of the profile's spendings over a period by Avito spending category: all, promotion, presence, commission, or rest. Read-only, spends no money (only shows already incurred spending). Period dateFrom..dateTo (YYYY-MM-DD). Note: grouping here is a STRING "day"|"week"|"month" (NOT an object, unlike items_post_item_analytics). Data depth no more than 270 days, no more than 1 request per minute. Required: dateFrom, dateTo, spendingTypes, grouping.

Returns aggregated CALL statistics for listings over a period (post_calls_stats) — total/new/answered/new answered, broken down by day. Read-only analytics, changes nothing and spends nothing. The period is set by dateFrom..dateTo (YYYY-MM-DD). Without itemIds — across all of the user's listings. For views/contacts, use items_post_item_stats_shallow.

Returns EXTENDED statistical metrics for the profile/listings over a period (post_item_analytics, stats v2): views, contacts, presenceSpending, etc. with flexible grouping, filters and sorting. Read-only analytics. Choose it over items_post_item_stats_shallow when you need filters by category/employee, sorting by a metric, or presence-spending metrics. limit ≤ 1000.

Returns counters (shallow statistics) for a list of listings over a period (post_item_stats_shallow / itemStatsShallow): unique views, contacts, favorites added. Read-only analytics. Use it for metrics on specific item_ids grouped by day/week/month; for extended profile analytics with filters and sorting, use items_post_item_analytics, and for calls, use items_post_calls_stats. Limits: no more than 200 listings per request, depth no more than 270 days back.

Returns the cost of promotion services (VAS), available packages and stickers for the given listings (post_vas_prices). Read-only — does NOT purchase and does NOT spend money, only a price reference. Always call it BEFORE purchasing via items_apply_vas / items_put_item_vas to learn the current service slugs and their prices.

Applies ONE additional promotion service (VAS) to a listing (put_item_vas). ⚠️ MONEY: charges money from the balance; irreversible. The response contains service data and the charged amount. DEPRECATED: for one or more services, prefer items_apply_vas (v2); for a package of services, use items_put_item_vas_package_v2. First call items_post_vas_prices for the current slug and price. Confirm with the user. Note: an error does not guarantee the service was not purchased — check again in a few minutes.

Applies a PACKAGE of promotion services (VAS) to a listing (put_item_vas_package_v2). ⚠️ MONEY: charges money from the balance; irreversible. The response contains the charged amount. Unlike items_put_item_vas (a single service by slug) and items_apply_vas (an arbitrary set of services/stickers), this method purchases a pre-assembled package by its package_id. DEPRECATED, the recommended replacement is items_apply_vas (v2). First check the price via items_post_vas_prices and confirm with the user. An error does not guarantee the package was not purchased — check again in a few minutes.

Changes a listing's price (update_price). ⚠️ PUBLIC: the new price is immediately visible to buyers on the site. Requires item_id and price (integer, in rubles). Available only for the Goods, Spare Parts, Auto and Real Estate categories (except short-term rentals); other categories return an error. Spends no money, but this is a live change to a public listing — confirm with the user. Limit: 150 requests/min.

Marks the unread messages of the specified chat as read, recording a read receipt and clearing the unread counter. Sends NOTHING to the other party and is not visible to them; does not modify or delete any message. Idempotent: calling it again on an already-read chat is safe. Requires chat_id (from messenger_get_chats_v2).

Deletes a SINGLE message from a chat by message_id. WARNING: IRREVERSIBLE — the message cannot be restored; the deletion is visible to the other party (a "deleted" marker remains in place of the message). You can usually delete only your own messages. Requires chat_id and message_id (from messenger_get_messages_v3). Always confirm with the user before calling.

Returns the details of a SINGLE chat by a known chat_id: participants, linked item, context, and the last message. Read-only. Use it when the chat_id is already known; to find a chat_id or get a list of conversations, use messenger_get_chats_v2. The conversation messages themselves are returned by messenger_get_messages_v3.

Returns a LIST of the account's chats (conversations with buyers) with a preview of the last message and an unread counter. Read-only — sends nothing and does not mark anything as read. Use it to find the needed chat_id before messenger_get_messages_v3, messenger_post_send_message or messenger_chat_read. To get the details of a single known chat, use messenger_get_chat_by_id_v2. Supports filters (items, types, unread) and offset-based pagination via limit/offset.

Returns the MESSAGES of a specific chat (V3), sorted newest to oldest: text, images, voice, links, date, and author. Read-only — does not mark the chat as read (use messenger_chat_read for that). Requires chat_id (from messenger_get_chats_v2). Page through a long conversation via limit/offset. For download URLs of voice files in messages, use messenger_get_voice_files.

Returns a LIST of the account's active webhook subscriptions: notification URLs and their versions/status. Read-only (despite the POST method — no body is required); creates and deletes nothing. Use it to check which URLs are subscribed before messenger_post_webhook_v3 (subscribe) or messenger_post_webhook_unsubscribe (unsubscribe).

Returns temporary download URLs for voice messages by their voice_id. Read-only. voice_id values come from voice messages obtained via messenger_get_messages_v3 (the voice/voice_id field). The links are temporary — download immediately.

Returns Avito messenger webhook events RECEIVED by this server (new chat messages), newest-first. Reads the in-process buffer filled by the webhook receiver — does NOT call the Avito API and does NOT mark anything as read. Requires the receiver to be enabled (set AVITO_MCP_WEBHOOK_SECRET) and Avito subscribed to the receiver URL (messenger_register_webhook). Supports filtering by chat_id, a `since` cutoff (ISO-8601 timestamp or epoch seconds/ms), and a `limit`. Check the receiver config and buffer stats with messenger_get_webhook_status.

Returns the configuration and live stats of this server's Avito webhook RECEIVER: whether it is enabled, the public URL, the subscribe URL (with the secret masked), and ring-buffer counters (retained / total / last received). Does NOT call the Avito API. Use it to verify the receiver is set up before messenger_register_webhook, then read collected events with messenger_get_webhook_events.

Adds one or more users to the account's BLACKLIST. WARNING: a blocked user will no longer be able to message you in the messenger; this immediately affects a third party and requires confirmation. Accepts an array of users with a user_id and an optional context (item_id and reason). reason_id: 1=spam, 2=fraud, 3=insults and rudeness, 4=other reason.

Sends an IMAGE (by an already-uploaded image_id) to a chat on behalf of the account. WARNING: the image is immediately and PUBLICLY visible to the other party. Two-step process: first upload the file via messenger_upload_images and obtain an image_id, then call this tool. For text, use messenger_post_send_message. Confirm sending with the user.

Sends a TEXT message to a chat on behalf of the account. WARNING: the message is immediately and PUBLICLY visible to the other party (the buyer) and is not removed automatically (you can delete it via messenger_delete_message). Confirm the text with the user before calling. Requires chat_id (from messenger_get_chats_v2) and text up to 1000 characters. To send an image, use messenger_post_send_image_message.

UNSUBSCRIBES the specified URL from messenger webhook notifications — Avito will stop sending events to this address. Changes account settings; to resume notifications you will have to subscribe again via messenger_post_webhook_v3. Specify exactly the URL that was subscribed (see the list in messenger_get_subscriptions).

SUBSCRIBES THIS server's operator-configured receiver URL to webhook notifications (V3) about new messenger events. For security, the URL must exactly match AVITO_MCP_WEBHOOK_PUBLIC_URL + path + secret; arbitrary destinations are rejected. Changes account settings and causes Avito to send future events externally, so confirmation is required by default. You can check current subscriptions via messenger_get_subscriptions and disable them via messenger_post_webhook_unsubscribe.

Subscribes Avito to THIS server's configured webhook receiver URL so messenger events (new chat messages) start flowing. Registers only the URL derived from the webhook config (AVITO_MCP_WEBHOOK_PUBLIC_URL + path + secret). Adds a webhook subscription (additive — it does not delete other subscriptions); Avito will then POST events to the URL (requires a PUBLIC HTTPS address reachable from the internet; localhost does not work). Same operation as messenger_post_webhook_v3, but auto-fills the URL from config. Pairs with messenger_get_webhook_events (read received events) and messenger_get_webhook_status (receiver config). To unsubscribe, use messenger_post_webhook_unsubscribe.