Skip to main content
Glama
pochta-russia-mcp

pochta-russia-mcp

by theYahia

MCP-сервер для Почты России — отслеживание посылок и расчёт доставки через ИИ

npm CI License: MIT

Если вы искали, как отследить отправление Почты России по трек-номеру из чата, посчитать тариф и срок доставки или найти индекс и ближайшее отделение — это оно. 6 инструментов: трекинг, расчёт стоимости и сроков, поиск отделений, индексы, нормализация адресов. Спрашиваете «где посылка 12345678901234» — получаете статус, а не страницу с капчей.

Возможности (6 инструментов)

Инструмент

Описание

Что требуется

track

Отслеживание отправления по трек-номеру

POCHTA_LOGIN + POCHTA_PASSWORD (SOAP-трекинг)

calculate

Расчёт стоимости и сроков доставки

POCHTA_TOKEN + POCHTA_LOGIN + POCHTA_PASSWORD

delivery_time

Расчёт сроков доставки между индексами

POCHTA_TOKEN + POCHTA_LOGIN + POCHTA_PASSWORD

get_offices

Поиск почтовых отделений

POCHTA_TOKEN + POCHTA_LOGIN + POCHTA_PASSWORD

zip_lookup

Информация по почтовому индексу

POCHTA_TOKEN + POCHTA_LOGIN + POCHTA_PASSWORD

normalize_address

Нормализация адреса через API

POCHTA_TOKEN + POCHTA_LOGIN + POCHTA_PASSWORD

Related MCP server: PostEx MCP Server

Быстрый старт

Claude Desktop / Cursor / Windsurf (stdio)

{
  "mcpServers": {
    "pochta": {
      "command": "npx",
      "args": ["-y", "@theyahia/pochta-russia-mcp"],
      "env": {
        "POCHTA_TOKEN": "<ACCESS_TOKEN>",
        "POCHTA_LOGIN": "<LOGIN>",
        "POCHTA_PASSWORD": "<PASSWORD>"
      }
    }
  }
}

Claude Code

claude mcp add pochta \
  -e POCHTA_TOKEN=<ACCESS_TOKEN> \
  -e POCHTA_LOGIN=<LOGIN> \
  -e POCHTA_PASSWORD=<PASSWORD> \
  -- npx -y @theyahia/pochta-russia-mcp

Streamable HTTP

npx @theyahia/pochta-russia-mcp --http --port=3000

MCP endpoint: http://localhost:3000/mcp Health check: http://localhost:3000/health → {"status":"ok","version":"…","tools":6}

Переменные окружения

Переменная

Обязательная

Описание

POCHTA_TOKEN

Да

Access-токен приложения → заголовок Authorization: AccessToken …

POCHTA_LOGIN

Да

Логин кабинета → часть X-User-Authorization: Basic …

POCHTA_PASSWORD

Да

Пароль кабинета → часть X-User-Authorization: Basic …

POCHTA_KEY

Нет

Back-compat: готовый base64(login:password) для X-User-Authorization (вместо LOGIN/PASSWORD)

POCHTA_TIMEOUT_MS

Нет

Таймаут запроса в мс (по умолчанию 15000)

Получите доступ к API: Кабинет отправителя → Настройки → API. Спецификация: https://otpravka.pochta.ru/specification.

Авторизация

REST-методы otpravka-api используют два заголовка (согласно официальной спецификации):

  • Authorization: AccessToken <POCHTA_TOKEN> — access-токен приложения;

  • X-User-Authorization: Basic <base64(POCHTA_LOGIN:POCHTA_PASSWORD)> — учётные данные кабинета.

Отслеживание (track) использует SOAP-API трекинга (tracking.russianpost.ru) и требует POCHTA_LOGIN + POCHTA_PASSWORD (access-токен там не применяется).

⚠️ Миграция на 2.0.0 (breaking change)

В версиях ≤ 1.x заголовки авторизации формировались неверно (access-токен и ключ были перепутаны местами), из-за чего REST-методы не проходили авторизацию. В 2.0.0 контракт исправлен:

  • Было: POCHTA_TOKEN + POCHTA_KEY. Этот набор больше не работает сам по себе.

  • Стало: POCHTA_TOKEN + POCHTA_LOGIN + POCHTA_PASSWORD.

  • POCHTA_KEY сохранён только как опциональный back-compat (готовый base64(login:password) для X-User-Authorization).

Надёжность

  • Повторные попытки (до 3) с экспоненциальной задержкой на сетевые ошибки, 429 и 5xx.

  • Таймаут запроса (по умолчанию 15 с, настраивается через POCHTA_TIMEOUT_MS).

  • Диагностические логи ретраев/ошибок пишутся в stderr (канал stdout занят MCP).

Skills (Claude Code)

Команда

Описание

/track <номер>

Отследить посылку Почты России

/calculate <от> <до> <вес>

Расчёт стоимости отправления

/parcel <от> <до> <вес>

Полный расчёт с ближайшим отделением

Тесты

npm install
npm run typecheck
npm test

Лицензия

MIT


Telegram: @vhodvai

Available Tools

6 tools
calculateC

Расчёт стоимости и сроков доставки Почтой России.

Inputs: weight (required), to_index (required), from_index (required), mail_type, +3 more.

delivery_timeB

Расчёт сроков доставки между двумя индексами.

Inputs: to_index (required), from_index (required), mail_type, mail_category.

get_officesB

Поиск почтовых отделений по индексу или населённому пункту.

Inputs: top, region, settlement, postal_code.

normalize_addressB

Нормализация адреса через API Почты России.

Inputs: raw_address (required).

trackA

Отслеживание почтового отправления Почты России по трек-номеру.

Inputs: barcode (required).

zip_lookupA

Информация по почтовому индексу: регион, город, график работы.

Inputs: postal_code (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 6 tools

    Disambiguation4/5

    Most tools have clear, distinct purposes: tracking, zip info, cost/delivery calculation, office search, delivery time, and address normalization. The only minor overlap is between 'calculate' (cost + delivery time) and 'delivery_time' (time only), but their descriptions clarify the difference.

    Naming Consistency5/5

    All tool names follow a consistent lowercase_with_underscores pattern. While some are verbs (track, calculate, get) and others are noun-based (zip_lookup, delivery_time, normalize_address), the style is uniform and predictable, making it easy to guess functionality.

    Tool Count5/5

    With 6 tools, the server is well-scoped for the Russian Post domain. Each tool addresses a distinct need—tracking, zip lookup, cost calculation, office search, delivery time, and address normalization—without excess or shortage.

    Completeness4/5

    The tool set covers the primary operations for Russian Post services, including tracking, address validation, cost/time estimation, and office lookup. Minor gaps exist, such as batch operations or detailed shipment history, but the core workflows are fully supported.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides tools for web, image, generative search, and Wordstat keyword statistics via Yandex Search API.
      7
      17 npm
      1
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Integrates with CDEK delivery API to manage orders, track shipments, find pickup points, and handle delivery labels and barcodes through natural language.
      49
      MIT
    • A
      license
      A
      quality
      F
      maintenance
      Enables integration with Boxberry delivery services, allowing users to search cities and pickup points, calculate delivery costs and times, track shipments, check postal indexes, and list services.
      6
      52 npm
      MIT