Кратко
API USPS для отправителей: проверка адресов в США и поиск почтовых индексов, сравнение внутренних и международных цен, получение дней доставки и вариантов доставки, отслеживание посылок и поиск почтовых отделений, пунктов сдачи и почтовых ящиков. Этикетки, возвраты, заборы и формы SCAN включены, но отключены. Ключ потребителя и секрет приложения в Портале по подключению клиентов USPS.
Пошаговая настройка
Подключи USPS к Cursor за 2 минуты
Начни бесплатный пробный период в AnythingMCP Cloud, подключи USPS в пошаговой настройке и добавь свой MCP URL в Cursor. Без кода и без собственного сервера.
Без банковской карты · 7 дней пробного периода · Есть вариант self-host
Попробуй спросить
Примеры промптов для USPS
Кликни по промпту — он скопируется. Вставь в Claude, ChatGPT, Cursor, Gemini, Copilot или OpenClaw и запусти через этот коннектор.
Claude — это AI, он может ошибаться. Проверяйте ответы.
💡 Нет установки? Используй cloud.anythingmcp.com напрямую. Войди в систему, нажми Connectors → USPS, вставь свои учетные данные, создай ключ API MCP, и всё готово. Никакого Docker, никакого
git clone, никакого локального сервера.
USPS + Cursor
API USPS для отправителей: проверка адресов в США и поиск почтовых индексов, сравнение внутренних и международных цен, получение дней доставки и вариантов доставки, отслеживание посылок и поиск почтовых отделений, пунктов сдачи и почтовых ящиков. Этикетки, возвраты, заборы и формы SCAN включены, но отключены. Ключ потребителя и секрет приложения в Портале по подключению клиентов USPS.
Предварительные требования
Смотри полные инструкции по настройке, встроенные в коннектор (видны в магазине приложения, когда ты выбираешь коннектор). Необходимые переменные окружения для этого коннектора:
USPS_CLIENT_ID, USPS_CLIENT_SECRET, USPS_API_HOST
Шаг 1 — Получи учетные данные
Настройка занимает около 15 минут.
- Открой Портал по подключению клиентов USPS по адресу https://cop.usps.com/cop-navigator?wf=API и войди в систему с помощью своей учетной записи USPS Business, или создай одну там. Портал подготавливает учетную запись для API USPS.
- Выбери My Apps в верхней части портала и добавь приложение.
- Открой приложение. В Credentials скопируй Consumer Key в
USPS_CLIENT_IDи Consumer Secret вUSPS_CLIENT_SECRET. - Выбери адрес API в
USPS_API_HOST: продуктивныйhttps://apis.usps.com, или Тестовую среду для отправителейhttps://apis-tem.usps.com. Оба используют одни и те же продуктивные учетные данные. Этикетки, созданные на тестовом хосте, имеют водяной знак и никогда не тарифицируются. USPS публикует тестовый хост для каждого API, кроме отслеживания, поэтому оставляй продуктивный, когда в основном отслеживаешь. - По желанию, для этикеток и контрактных цен: твой CRID, Mailer ID и номер счета Enterprise Payment Account в
USPS_CRID,USPS_MIDиUSPS_EPS_ACCOUNT_NUMBER. Их имеет администратор бизнес-услуг твоей учетной записи Business Customer Gateway.
Коннектор отправляет ключ потребителя и секрет на /oauth2/v3/token на выбранном хосте (учетные данные клиента) и получает токен доступа, действительный примерно 8 часов, который он повторно использует и обновляет самостоятельно.
Что может использовать новое приложение: каждое приложение начинается с продукта по умолчанию USPS: OAuth, Адреса, Внутренние цены, Международные цены, Локации, Стандарты обслуживания, Варианты доставки и Отслеживание. Адреса, цены, дни доставки, варианты доставки, отслеживание, почтовые отделения и пункты сдачи, таким образом, работают сразу. Забор курьером, платежи, этикетки и формы SCAN требуют одобрения USPS: запроси их с помощью запроса на обслуживание API USPS на странице Email Us (https://emailus.usps.com/s/usps-APIs). API этикеток также требуют регистрации в USPS Ship (выходные и возвратные этикетки) и Enterprise Payment Account (EPS), который оплачивает почтовые расходы. Почтовые ящики (usps_find_parcel_lockers) и международный стандарт обслуживания (usps_get_international_service_standard) имеют свои собственные области; если они отвечают 403, запроси их у USPS тем же способом.
С чего начать: usps_get_city_state с почтовым индексом подтверждает соединение. Для запроса usps_search_shipping_options возвращает цены и даты доставки для каждой услуги за один вызов; usps_search_domestic_prices и usps_search_international_prices дают разбивку цен с дополнительными услугами.
Адреса: usps_validate_address стандартизирует адрес в США и возвращает ZIP+4, DPVConfirmation (Y подтвержден, D отсутствует вторичный номер, S вторичный номер не подтвержден, N не подтвержден), business (Y или N) и vacant. usps_get_zip_code находит почтовый индекс улицы в городе и штате, usps_get_city_state — город и штат почтового индекса. Штаты — это двухбуквенные коды; только адреса США (включая территории и военные адреса) охватываются.
Цены: посылки взвешиваются в фунтах и измеряются в дюймах; письма, плоские конверты и открытки взвешиваются в унциях. price_type COMMERCIAL — это то, что ты платишь за этикетки, купленные онлайн, RETAIL — это цена на стойке почтового отделения, CONTRACT требует account_type и account_number. usps_search_domestic_prices возвращает rateOptions с totalBasePrice, totalPrice и дополнительными услугами; usps_list_domestic_prices перечисляет каждый подходящий продукт с его SKU, rateIndicator и processingCategory, значениями, необходимыми для запроса этикетки. usps_search_letter_prices оценивает письма первого класса. За границей: usps_search_international_prices (по желанию с пошлинами и налогами на каждый товар), usps_list_international_prices и usps_search_international_letter_prices. Даты отправки могут быть сегодня или до 7 дней вперед. Суммы указаны в долларах США. USPS_GROUND_ADVANTAGE заменил службу первого класса и розничную наземную доставку.
Дни доставки: usps_get_delivery_estimates дает запланированную дату доставки для дня отправки, с временем окончания приема (cutOffTime, HHMM местное); usps_get_service_standards стандартное количество дней для каждого класса почты; usps_get_international_service_standard предложение, например, Ожидаемая доставка через 5-9 рабочих дней. Стандарт обслуживания — это цель, а не гарантия.
Отслеживание: usps_track_package для одного номера, usps_track_packages для до 35 одновременно. Оба используют отслеживание 3.2; устаревший API отслеживания 3.0 будет отключен 31 июля 2027 года. Ответ содержит statusCategory, statusSummary, trackingEvents (eventTimestamp в местном времени события, GMTTimestamp в UTC), deliveryDateExpectation и uniqueTrackingID. Пакетный ответ возвращает HTTP 207, когда некоторые номера не проходят, и каждый неудавшийся номер имеет свой собственный error. usps_register_tracking_notifications подписывает до 3 адресов электронной почты для отслеживания и usps_request_proof_of_delivery отправляет письмо с подтверждением доставки по электронной почте; оба требуют uniqueTrackingID из ответа отслеживания, отправляют электронную почту от USPS и ничего не стоят.
Локации: usps_find_post_offices ищет по почтовому индексу, городу и штату, адресу или координатам (радиус в милях, по умолчанию 20) и перечисляет часы работы каждой службы; usps_find_dropoff_locations перечисляет пункты сдачи для Parcel Select, USPS Connect и Package Services по почтовому индексу назначения; usps_find_parcel_lockers находит почтовые ящики.
Заборы: usps_check_pickup_eligibility и usps_get_pickup только для чтения. usps_schedule_pickup бронирует бесплатный забор курьером (с понедельника по субботу), а usps_cancel_pickup отменяет его; оба отключены. Забор нельзя изменить здесь: отмени его и забронируй новый.
Этикетки (отключены): каждый вызов этикетки требует токен авторизации платежа. usps_create_payment_authorization с твоим CRID, Mailer ID и EPS счетом возвращает paymentAuthorizationToken; передай его в usps_create_label, usps_create_return_label, usps_create_international_label, usps_cancel_label или usps_cancel_international_label. Этикетки возвращаются в формате JSON: labelMetadata с номером отслеживания и почтовыми расходами, и labelImage в base64 (по умолчанию PDF 4x6). Создание этикетки покупает почтовые расходы с EPS счета. Отмена возвращает CANCELED или DISPUTED с disputeId, когда USPS открыл запрос на возврат. usps_get_payment_account читает счет и, с amount, сообщает, достаточно ли средств. usps_create_scan_form объединяет множество этикеток в одну форму PS Form 5630 для единого сканирования при приеме. Включай эти инструменты только после того, как USPS одобрит API этикеток, и сначала попробуй их на тестовом хосте.
Ошибки: сбои приходят как error с code, message и списком errors (title, detail, source.parameter). 400 указывает на неправильное поле; 401 означает неправильные учетные данные или истекший токен; 403 означает, что у приложения нет этого API (он вне продукта по умолчанию); 404 означает, что USPS ничего не нашел, например, неизвестный номер отслеживания.
Лимиты: каждое приложение имеет квоту вызовов в час; 429 означает, что она исчерпана до следующего часа. USPS увеличивает квоту по запросу через страницу Email Us. Даты в формате YYYY-MM-DD.
Шаг 2 — Установи адаптер
curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d
Шаг 3 — Добавь коннектор в Cursor
URL вашего сервера: в AnythingMCP откройте MCP Servers → сервер, на котором находится этот коннектор, и скопируйте его URL (
https://cloud.anythingmcp.com/mcp/…). Используйте его везде, где в этом руководстве указаноYOUR_SERVER_ID.
Cursor читает MCP-серверы из ~/.cursor/mcp.json. Добавь эту запись:
{
"mcpServers": {
"anythingmcp": {
"url": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
"headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
}
}
}
- Создай MCP API-ключ в AnythingMCP в разделе MCP Servers → твой сервер → API keys и вставь его вместо
YOUR_MCP_API_KEY. - Сохрани файл и перезапусти Cursor.
- Открой Cursor → Settings → MCP и проверь, что
anythingmcpесть в списке и подключён. - Начинай общаться: агент теперь может вызывать инструменты
USPS.
Доступные инструменты
| Инструмент | Что он делает |
|---|---|
usps_validate_address | Проверяет и стандартизирует один адрес в США. Возвращает address в стандартной форме USPS (streetAddress, city, state, ZIPCode, ZIPPlus4)… |
usps_get_city_state | Находит город и штат по 5-значному почтовому индексу. Возвращает city (в верхнем регистре), state (две буквы) и ZIPCode. Дешевый вызов, используется как… |
usps_get_zip_code | Находит почтовый индекс и ZIP+4 для адреса улицы в городе и штате. Возвращает address со стандартизированной улицей, city, state… |
usps_search_domestic_prices | Оценивает внутреннюю посылку по классам почты, включая дополнительные услуги. Возвращает rateOptions, по одному для каждого подходящего продукта, каждый с… |
usps_list_domestic_prices | Перечисляет каждый продукт, на который подходит внутренняя посылка, с его базовой ценой и без дополнительных услуг. Возвращает rateOptions с… |
usps_search_letter_prices | Оценивает письмо первого класса, плоский конверт (большой конверт) или открытку, отправленную внутри США. Возвращает totalBasePrice и rates (SKU… |
usps_search_international_prices | Оценивает исходящую международную посылку, включая дополнительные услуги и, по запросу, пошлины и налоги на каждый товар. Возвращает rateOptions, по одному для… |
usps_list_international_prices | Перечисляет каждый международный продукт, на который подходит исходящая посылка, с базовыми ценами и без дополнительных услуг. Возвращает rateOptions с… |
usps_search_international_letter_prices | Оценивает международное письмо первого класса, плоский конверт или открытку. Возвращает totalBasePrice, rates (SKU, description, price, fees)… |
usps_get_delivery_estimates | Оценивает дату доставки почты, принятой в определенный день. Возвращает список, по одной записи для каждого класса почты, с serviceStandard (дни)… |
usps_get_service_standards | Получает стандартное количество дней доставки между двумя почтовыми индексами по классам почты. Возвращает список с mailClass, days… |
usps_get_international_service_standard | Получает ожидаемое время доставки международного класса почты в страну. Возвращает countryCode, mailClass и… |
usps_search_shipping_options | Сравнивает все способы отправки одной посылки за один вызов: цены и обязательства по доставке вместе, внутренние или международные. Возвращает… |
usps_track_package | Отслеживает одну посылку USPS с помощью отслеживания 3.2. Возвращает trackingNumber, uniqueTrackingID, mailClass, status, statusCategory (например,… |
usps_track_packages | Отслеживает до 35 посылок USPS за один вызов с помощью отслеживания 3.2. Возвращает один результат для каждого номера с trackingNumber, uniqueTrackingID… |
usps_register_tracking_notifications | Подписывает до 3 адресов электронной почты для отслеживания USPS о одной посылке: ожидаемые обновления доставки, активность доставки или все обновления. Требует… |
usps_request_proof_of_delivery | Отправляет USPS письмо с подтверждением доставки (или электронную квитанцию о возврате) для доставленной посылки до 3 получателей. Требует… |
usps_find_post_offices | Находит почтовые отделения и другие розничные точки рядом с почтовым индексом, адресом или координатами, ближайшие сначала. Возвращает locations с… |
usps_find_dropoff_locations | Находит пункты сдачи, где ты можешь сдать почту Parcel Select, USPS Connect и Package Services для почтового индекса назначения… |
usps_find_parcel_lockers | Находит почтовые ящики USPS по почтовому индексу или по городу и штату. Возвращает список ящиков с facilityID, locationName, locationAddress… |
usps_check_pickup_eligibility | Проверяет, предлагает ли USPS бесплатный забор курьером по адресу. Ответ 200 с pickupAddress в стандартизированной форме, когда адрес… |
usps_get_pickup | Получает запланированный забор курьером по номеру подтверждения. Возвращает confirmationNumber, pickupDate и carrierPickupRequest (адрес… |
usps_get_payment_account | Проверяет счет Enterprise Payment Account или разрешение. Возвращает данные счета и, когда указано amount, sufficientFunds (true или false)… |
usps_create_payment_authorization | Получает токен авторизации платежа, который требуется для каждого вызова этикетки: указывает твой бизнес как PAYER и LABEL_OWNER с его CRID, Mailer ID и… |
usps_create_label | Покупает почтовые расходы и создает этикетку для внутренней доставки, оплачиваемую с счета Enterprise Payment Account в токене авторизации платежа. Возвращает… |
usps_create_return_label | Создает этикетку для возврата для клиента, чтобы отправить посылку обратно (to_address — это твой адрес возврата, from_address — адрес клиента).… |
usps_cancel_label | Отменяет неиспользуемую внутреннюю этикетку или запрашивает возврат почтовых расходов. Возвращает trackingNumber, status (CANCELED или DISPUTED, когда запрос на возврат… |
usps_create_international_label | Покупает почтовые расходы и создает международную этикетку с ее таможенной формой (First-Class Package International Service, Priority Mail International… |
usps_cancel_international_label | Отменяет неиспользуемую международную этикетку или запрашивает возврат почтовых расходов. Возвращает номер отслеживания, status (CANCELED или DISPUTED) и… |
usps_schedule_pickup | Бронирует бесплатный забор курьером USPS для посылок по твоему адресу (с понедельника по субботу; только в тот же день до 2 часов ночи по центральному времени). Возвращает… |
usps_cancel_pickup | Отменяет запланированный забор курьером по номеру подтверждения. Возвращает 200 при отмене. Установлено отключенным: отмены остаются с… |
usps_create_scan_form | Создает форму SCAN (PS Form 5630), которая связывает этикетки с одним штрих-кодом, так что одно сканирование при приеме фиксирует каждую посылку. Возвращает… |
Примеры подсказок
- "Где посылка USPS 9400111899223197428490?"
- "Является ли 1600 Pennsylvania Ave NW, Washington DC 20500 действительным адресом, и каков его ZIP+4?"
- "Сравни цены USPS и даты доставки для коробки весом 3 фунта из 10001 в 94105, отправленной завтра."
- "Сколько стоит посылка весом 2 фунта в Торонто с помощью USPS Priority Mail International?"
- "Найди почтовые отделения, открытые в субботу, рядом с ZIP 60614."
Часто задаваемые вопросы
Откуда берутся учетные данные USPS? Из приложения в Портале по подключению клиентов USPS (cop.usps.com), войдя в систему с помощью своей учетной записи USPS Business: открой My Apps, добавь приложение и скопируй его Consumer Key и Consumer Secret. Выбери продуктивный хост или Тестовую среду для отправителей; оба используют одни и те же учетные данные.
Что работает сразу, а что требует одобрения USPS? Адреса, цены, дни доставки, варианты доставки, отслеживание и локации работают с каждым новым приложением. Забор курьером, платежи, этикетки и формы SCAN требуют одобрения USPS через запрос на обслуживание API USPS; этикетки также требуют USPS Ship и Enterprise Payment Account.
Какие инструменты устанавливаются отключенными? Инструменты, которые покупают или бронируют: usps_create_payment_authorization, usps_create_label, usps_create_return_label, usps_cancel_label, usps_create_international_label, usps_cancel_international_label, usps_schedule_pickup, usps_cancel_pickup и usps_create_scan_form. Включай их на странице коннектора, как только USPS одобрит их, и AI должен использовать их.
Поддерживает ли Cursor собственные MCP-серверы на бесплатном тарифе? Да — MCP доступен на тарифах Hobby, Pro и Business.
Следующие шаги
Это руководство помогло?