Novaposhta MCP server

Read from the package source without running it. The installed server may list more.

• address_deletewrite action

  Delete counterparty address by reference using Address/delete (doc 1.25). Allowed only before the address participates in an Internet document; afterward the API blocks deletion.

• address_get_settlement_country_region

  Get settlement country regions (\u0440\u0435\u0433\u0456\u043E\u043D\u0456\u0432) for a specific area via Address/getSettlementCountryRegion (doc 1.3). Returns list of regions within an administrative area. Requires areaRef parameter. Docs recommend caching for 12 hours.

• address_get_settlements

  Get settlement areas (\u043E\u0431\u043B\u0430\u0441\u0442\u0435\u0439) via Address/getSettlementAreas (doc 1.3). Returns list of administrative regions/areas in Ukraine. Docs recommend caching this public directory for 12 hours.

• address_get_warehouses

  List Nova Poshta warehouses (branches, postomats, pickup points) via Address/getWarehouses (doc 1.5). Docs emphasize caching the branch directory daily to leverage schedule arrays, max weight limits, and warehouse types without re-fetching thousands of rows. IMPORTANT: Always use limit parameter (recommended: 10-20) to avoid large responses.

• address_savewrite action

  Create new address for a counterparty via Address/save (doc 1.24). Requires API key plus CounterpartyRef, StreetRef, BuildingNumber; response returns the Ref and Description needed for door-to-door delivery.

• address_search_cities

  Find Nova Poshta cities by name or postal index using Address/getCities (doc 1.3). Docs note the city directory is public (no API key) but must be cached and refreshed daily because it exposes Area and Delivery1-Delivery7 flags. IMPORTANT: Always use limit parameter (recommended: 10) to avoid large responses.

• address_search_settlements

  Search for settlements (city, town, village) with pagination over the same Address/getCities dataset described in doc 1.3 (Area + Delivery1-Delivery7 fields, daily refresh recommended). IMPORTANT: Always use limit parameter (recommended: 10) to avoid large responses.

• address_search_streets

  Search for streets inside a settlement via Address/getStreet (doc 1.4). Used for door pickup/delivery flows, limited to 500 records per page, public but should be cached and refreshed daily. IMPORTANT: Always use limit parameter (recommended: 10) to avoid large responses.

• address_updatewrite action

  Update existing counterparty address with Address/update (doc 1.25). Nova Poshta docs stress you can edit an address only until a waybill is created with it, so run this immediately after address creation.

• contact_person_deletewrite action

  Delete contact person by reference using ContactPerson/delete (doc 1.27). Nova Poshta allows deletions via API only for legal entities and only until the contact was used on an Internet document.

• contact_person_savewrite action

  Create new contact person for a counterparty via ContactPerson/save (doc 1.26). Docs require entering all fields in Ukrainian and with an API key; response returns the Ref/Description pair referenced in waybills.

• contact_person_updatewrite action

  Update existing contact person details via ContactPerson/update (doc 1.27). Only legal entities may edit full profiles, private persons can change phone only, and edits are allowed solely before a waybill is issued for that counterparty.

• counterparty_deletewrite action

  Delete counterparty by reference using Counterparty/delete (doc 1.22). IMPORTANT: Docs explicitly state only Recipient counterparties can be deleted through the API; Sender cleanup must go through your account manager.

• counterparty_get_addresses

  Get addresses for a specific counterparty using Counterparty/getCounterpartyAddresses (doc 1.6). Requires API key plus CounterpartyProperty/Ref and, per docs, should be refreshed daily because every page is capped at 500 entries.

• counterparty_get_contact_persons

  Get contact persons for a counterparty through Counterparty/getCounterpartyContactPersons (doc 1.6). API key is mandatory and the list should be cached daily; use paging to stay under the 500-record response cap.

• counterparty_get_counterparties

  Get counterparties list filtered by property (Sender/Recipient/ThirdPerson) via Counterparty/getCounterparties (doc 1.6). Docs require an API key, recommend caching the directory daily, and note each page tops out at 500 rows so always filter with CounterpartyProperty/FindByString.

• counterparty_get_options

  Get counterparty options and permissions via Counterparty/getCounterpartyOptions (doc 1.23) to see booleans such as CanPayTheThirdPerson, CanSameDayDelivery, HideDeliveryCost, etc., before building a waybill.

• counterparty_savewrite action

  Create new counterparty (private person or organization) with Counterparty/save (docs 1.20\u20131.21). Provide CityRef + CounterpartyProperty/Type; private persons require first/last name while organizations must also send OwnershipForm and EDRPOU. Docs recommend refreshing supporting directories monthly and note an API key is required.

• counterparty_updatewrite action

  Update existing counterparty details via Counterparty/update (doc 1.22). Nova Poshta only lets you edit a counterparty from creation up until you create a waybill (\u0406\u0414) with it, so run updates early.

• get_document_list

  List documents created in the given date range. Per doc 1.2, these queries target the InternetDocument model used for \u043E\u0444\u043E\u0440\u043C\u043B\u0435\u043D\u043D\u044F \u0432\u0456\u0434\u043F\u0440\u0430\u0432\u043B\u0435\u043D\u044C, so date filters help keep the success/data/errors response manageable.

• get_document_movement

  Get movement history for up to 10 documents including statuses and timestamps. Doc 1.2 identifies InternetDocument numbers as the primary shipment identifiers, which this endpoint accepts in batches.

• reference_decode_message

  Decode Nova Poshta API message code into human readable text. Doc 1.2 explains how every response contains success/data/errors/warnings/info blocks with numeric codes; this helper calls getMessageCodeText to map those codes to UA/RU descriptions.

• reference_get_backward_cargo_types

  List backward delivery cargo types via Common/getBackwardDeliveryCargoTypes (doc 1.18). Returns types of cargo that can be sent back (documents, money, etc.). Used for return shipments and COD. Docs recommend caching monthly.

• reference_get_cargo_description_list

  List cargo descriptions with optional search via Common/getCargoDescriptionList (doc 1.15). Returns predefined descriptions for common cargo types. Supports search by keyword. Docs recommend caching monthly.

• reference_get_cargo_types

  List available cargo types supported by Nova Poshta via Common/getCargoTypes (doc 1.8). Docs advise caching this API-key-protected directory monthly; expect values such as Parcel, Cargo, Documents, TiresWheels, Pallet.

• reference_get_ownership_forms

  List corporate ownership forms required for counterparty creation via Common/getOwnershipFormsList (doc 1.11). Docs provide both short and full names for refs such as \u0422\u041E\u0412, \u041F\u0440\u0410\u0422, \u0424\u0413 and recommend a monthly refresh.

• reference_get_pack_list

  List available packaging types via Common/getPackList (doc 1.10). Returns standard package dimensions and descriptions. Useful for calculating delivery costs and validating package options. Docs recommend caching monthly.

• reference_get_pallet_types

  List pallet types with dimensions and weight via Common/getPalletsList (doc 1.13). Refresh monthly per docs, especially when offering reverse delivery of pallets.

• reference_get_payment_forms

  Get list of payment forms (Cash/NonCash) for waybill creation with Common/getPaymentForm (doc 1.7). Nova Poshta notes non-cash payments are available only to contracted clients, so keep a cached copy to validate user choices.

• reference_get_payment_methods

  List supported payment methods for shipments (Cash/NonCash) matching the Common/getPaymentForm directory from doc 1.7, which notes that non-cash payments are only available to customers with a Nova Poshta contract.

• reference_get_pickup_time_intervals

  Get available pickup time intervals via Common/getPickupTimeIntervals (doc 1.17). Returns time windows when Nova Poshta can pick up packages from sender. Requires city reference and date. Docs recommend caching hourly.

• reference_get_redelivery_payers

  List payer types for redelivery via Common/getTypesOfPayersForRedelivery (doc 1.19). Returns who can pay for backward delivery (Sender/Recipient). Used with return shipments. Docs recommend caching monthly.

• reference_get_service_types

  List delivery service types (warehouse-door etc.) through Common/getServiceType (doc 1.9). Docs say to refresh monthly and point out the four core technologies: WarehouseWarehouse, WarehouseDoors, DoorsWarehouse, DoorsDoors.

• reference_get_time_intervals

  Get available delivery time intervals for recipient city using Common/getTimeIntervals (doc 1.16). Requires RecipientCityRef (and optional DateTime) and returns Number/Start/End entries that docs recommend caching monthly.

• reference_get_tires_wheels_list

  List available tires and wheels types via Common/getTiresWheelsList (doc 1.12). Returns types and descriptions for shipping tires and wheels as cargo. Docs recommend caching monthly.

• reference_get_types_of_counterparties

  Get list of counterparty types (PrivatePerson/Organization) via Common/getTypesOfCounterparties (doc 1.14). Requires API key and, per docs, should be refreshed monthly to stay aligned with sender/recipient onboarding rules.

• reference_get_types_of_payers

  Get list of payer types (Sender/Recipient/ThirdPerson) for waybill creation via Common/getTypesOfPayers (doc 1.7). Docs stress the ThirdPerson payer is accessible only after signing a service contract and that the directory should be cached monthly.

• track_document

  Track a single Nova Poshta document by number and optional phone to receive live status, location, and ETA. Doc 1.2 describes the standard success/data/errors/warnings/info envelope returned by Nova Poshta, which this helper surfaces back to the caller.

• track_multiple

  Track multiple Nova Poshta documents with organized results and statistics via TrackingDocument/getStatusDocuments (doc 1.2). Returns successful/failed tracking attempts with delivery statistics (delivered, in-transit, at-warehouse counts). More convenient than track_multiple_documents for batch operations.

• track_multiple_documents

  Track multiple Nova Poshta documents at once and receive aggregated statistics. Doc 1.2 states every API call returns the same envelope, so use the success/errors/warnings fields here to mirror the native batch tracking response.

• waybill_calculate_cost

  Calculate delivery cost and optional delivery date estimation for a shipment. Doc 1.2 explains that every Nova Poshta call sends apiKey/modelName/calledMethod/methodProperties, so this helper either forwards your raw InternetDocument payload or builds one from typed fields (CitySender, CityRecipient, ServiceType, CargoType, Cost, Weight, SeatsAmount).

• waybill_createwrite action

  Create a standard Nova Poshta waybill (Internet document) via InternetDocument/save (doc 1.2). This is the basic waybill creation method. For additional services use waybill_create_with_options. For postomat delivery use waybill_create_for_postomat.

• waybill_create_batchwrite action

  Batch create multiple waybills sequentially via InternetDocument/save (doc 1.2). Processes each waybill one by one to avoid rate limiting. Returns array of results including any errors. Useful for bulk shipment creation.

• waybill_create_for_postomatwrite action

  Create a waybill for postomat delivery via InternetDocument/save (doc 1.2). Postomats have size/weight restrictions (max 30kg, max dimensions). Requires proper warehouse selection (postomat type) and seat options configuration.

• waybill_create_with_optionswrite action

  Create a Nova Poshta waybill with additional options and services via InternetDocument/save (doc 1.2). Supports backward delivery, additional services, third-party payer, and RedBox barcodes. Use this when you need COD, insurance, or return shipments.

• waybill_deletewrite action

  Delete one or multiple waybills by their DocumentRef via InternetDocument/delete (doc 1.2). Waybills can only be deleted before they enter processing. Returns success/error status for the operation.

• waybill_delete_batchwrite action

  Batch delete multiple waybills by their DocumentRef via InternetDocument/delete (doc 1.2). Alias for waybill_delete that processes all refs in a single API call. Waybills can only be deleted before they enter processing.

• waybill_get_delivery_date

  Get estimated delivery date for a city pair and service type. Doc 1.2 outlines the generic Nova Poshta envelope, and this helper builds the methodProperties (CitySender, CityRecipient, ServiceType, optional DateTime) expected by the delivery-date method.

• waybill_get_estimate

  Get complete shipment estimate (price + delivery date) in one call via InternetDocument/getDocumentPrice and getDocumentDeliveryDate (doc 1.2). Combines cost calculation and delivery date estimation for convenience. Requires the same PascalCase parameters as waybill_calculate_cost.

• waybill_updatewrite action

  Update an existing waybill. Per doc 1.2 the same InternetDocument request envelope is used for update calls, so pass the raw payload (must include DocumentRef) exactly as defined by Nova Poshta.

• Code scan23 source files scanned25/25
• –Live reliabilityno gateway calls yet and no remote to proben/a
• –Tool poisoningtools not inspected (local package is not executed); not countedn/a
• Auth qualitystatic API keys via environment variables6/15
• Maintenancelast push 4 days ago15/15
• Maintainer identityregistry namespace matches repository owner7/10

Safety score

82/100

higher than 63% of 48,255 servers

Tools

50

the typical server has 7

Tools that change things

32%

typical: 0%. Fewer write tools means less an agent can break

GitHub stars

7

more than 86% of 28,688 servers

Novaposhta: common questions

Is Novaposhta MCP server safe?

Mostly: it is graded B (82/100). Read the Novaposhta safety report

How do I install Novaposhta?

It runs on your machine. Copy the Claude Code, Cursor, VS Code or Claude Desktop config from the install section.

Does Novaposhta need an API key?

Yes. The registry entry asks for NOVA_POSHTA_API_KEY.

Is Novaposhta maintained?

The last commit was 37 days ago (2026-09-28). The latest release is v0.0.1-alpha.7.

How does Novaposhta compare with other MCP servers?

safety score 82/100 (higher than 63% of 48,255 servers); tools 50 (the typical server has 7); tools that change things 32% (typical: 0%. Fewer write tools means less an agent can break). Full comparison.