usaspending-gov-mcp

Бесплатный MCP-сервер с открытым исходным кодом для API USAspending.gov: контракты, гранты, займы, субподряды, получатели финансирования, ведомства и федеральные счета.

Обзор, демонстрационное видео и настройка размещённой версии: https://1102tools.com/mcp/usaspending

API-ключ не требуется ни для локального, ни для размещённого варианта. См. раздел «Локальная или размещённая версия».

Регрессионные тесты, включая проверку работы с API USAspending. Выпуски за октябрь 2026 года также проверены на реалистичных вопросах о закупках по всем 55 инструментам: история контрактов, итоги за финансовые годы, отчёты о субподрядах и федеральные счета. См. testing.md.

Локальная или размещённая версия

Локальная (для компьютера)	Claude (размещённая)	ChatGPT (размещённая)
Локальная настройка	Установить	Установить

• Локальная версия запускается на вашем компьютере — в настольном приложении Claude или ChatGPT либо в другом AI-приложении. Вы получаете собственные полные лимиты запросов, а сервер обращается только к государственному сервису. Автоматически он не обновляется, поэтому попросите AI обновить его. Настраивать всё вручную не обязательно: отправьте AI ссылку на эту страницу и попросите установить сервер или провести вас через настройку.

• Размещённая версия всегда обновлена, не требует настройки и ключей и доступна в Claude или ChatGPT из любого места.

Сравнение локальной и размещённой версий · Подходящие запросы

Возможности

Предоставляет доступ к REST API USAspending.gov через 55 инструментов MCP:

Поиск и агрегирование

• search_awards — основной поиск контрактов, IDV, грантов, займов и прямых выплат

• Фильтр program_numbers — позволяет ограничить поиск грантов, займов и других видов помощи номером программы (CFDA), например 93.778 для Medicaid. Доступен в инструментах search_awards, get_award_count, spending_over_time, spending_by_category, spending_by_subaward_grouped, spending_by_transaction и spending_by_geography. Найти номера по названию программы можно с помощью autocomplete_cfda.

• get_award_count — подсчёт по категориям федерального финансирования и другим параметрам

• spending_over_time — агрегирование данных по периодам: финансовым годам, кварталам и месяцам

• spending_by_category — разбивка по крупнейшим категориям: ведомствам, поставщикам, NAICS, PSC, штатам и другим параметрам

• spending_by_transaction — поиск транзакций на уровне изменений к контракту

• spending_by_geography — разбивка по штатам, округам и избирательным округам Конгресса

• new_awards_over_time — динамика новых контрактов получателя

Сведения о контракте или финансировании

• get_award_detail — полная запись об отдельном контракте или виде финансирования

• get_transactions — полная история изменений по контракту

• get_award_funding — данные о финансировании из File C: счета Казначейства, категории расходов и программная деятельность

• get_award_funding_rollup — сводка по финансированию в одной строке

• get_award_subaward_count, get_award_federal_account_count, get_award_transaction_count

• get_idv_children — заказы на выполнение работ или поставку по IDV

• awards_last_updated — проверка актуальности данных

Субподряды (FFATA)

• search_subawards — поиск субподрядов в рамках одного основного контракта

• spending_by_subaward_grouped — поиск основных контрактов с суммарными данными об указанных субподрядах

Получатели финансирования

• search_recipients — поиск получателей по ключевым словам

• get_recipient_profile — полная запись о получателе

• get_recipient_children — дочерние компании головного получателя

• autocomplete_recipient — поиск названий получателей по части названия

• list_states — все штаты с кодами FIPS

В рабочем процессе для поиска сведений о получателе используйте название из autocomplete_recipient в запросе к

search_recipients. Для получения профиля и данных о новых контрактах используйте возвращённый хеш id. Чтобы найти дочерние компании, передайте в get_recipient_children значение uei (или устаревшее duns) из строки родительской компании (-P); этот инструмент принимает UEI и DUNS.

Подробные сведения о ведомствах

• list_toptier_agencies, get_agency_overview, get_agency_awards

• get_agency_budgetary_resources — бюджетные ресурсы по финансовым годам

• get_agency_sub_agencies — подведомственные организации и их обязательства

• get_agency_federal_accounts — источники финансирования (TAS)

• get_agency_object_classes — категории расходов (OMB)

• get_agency_program_activities — разбивка по программам

• get_agency_obligations_by_award_category — соотношение контрактов и грантов

Подробные сведения об IDV

• get_idv_amounts — сводные данные по IDV

• get_idv_funding, get_idv_funding_rollup — данные File C для IDV

• get_idv_activity — заказы, оформленные в рамках IDV

Федеральные счета (Казначейство)

• list_federal_accounts — поиск по TAS

• get_federal_account_detail, get_federal_account_object_classes,

get_federal_account_program_activities, get_federal_account_fy_snapshot

Автодополнение

• autocomplete_psc, autocomplete_naics

• autocomplete_awarding_agency, autocomplete_funding_agency

• autocomplete_cfda (гранты), autocomplete_glossary, autocomplete_recipient

Справочные данные

• get_naics_details, get_psc_filter_tree

• get_award_types_reference — все коды типов федерального финансирования (A = вызов BPA и т. д.)

• get_def_codes_reference — коды фондов для чрезвычайных ситуаций и ликвидации последствий стихийных бедствий (COVID, IIJA, IRA)

• get_glossary — терминология в сфере закупок и расходов

• get_submission_periods — охват отчётных периодов ведомств

• get_state_profile — профиль расходов на уровне штата

Инструменты для упрощения рабочих процессов

• lookup_piid — автоматически определяет, относится ли номер к контракту или IDV, и возвращает соответствующую запись

Установка

Через pip

pip install usaspending-gov-mcp

Через uvx (рекомендуется, виртуальное окружение не требуется)

uvx --refresh-package usaspending-gov-mcp --from usaspending-gov-mcp usaspending-mcp

Параметр --from требуется только для этого сервера. Имя пакета на PyPI —

usaspending-gov-mcp, а устанавливаемый им исполняемый скрипт называется usaspending-mcp,

поэтому простая команда uvx usaspending-gov-mcp завершается ошибкой: «Пакет usaspending-gov-mcp не предоставляет исполняемый файл с именем

usaspending-gov-mcp».

Не запускайте и uvx usaspending-mcp. На PyPI это имя принадлежит стороннему пакету, не связанному с данным проектом.

Из исходного кода

git clone https://github.com/1102tools-dev/federal-contracting-mcps.git
cd federal-contracting-mcps/servers/usaspending-gov-mcp
pip install -e .

Настройка

Используйте приведённую ниже конфигурацию для описания сервера и разместите её в соответствии с требованиями вашего MCP-клиента. Примеры запросов к этому источнику доступны в библиотеке промптов.

{
  "mcpServers": {
    "usaspending": {
      "command": "uvx",
      "args": ["--refresh-package", "usaspending-gov-mcp", "--from", "usaspending-gov-mcp", "usaspending-mcp"]
    }
  }
}

Флаг --refresh-package указывает uv проверять PyPI на наличие новой версии при каждом запуске сервера клиентом. Благодаря этому исправления устанавливаются автоматически. Без этого флага uv продолжит использовать версию, которую сохранил в кэше при первом запуске. Проверка добавляет небольшую задержку из-за обращения к сети. Если на вашей платформе установлен короткий лимит времени запуска MCP-сервера, увеличьте его.

Если вы установили пакет с помощью pip install -e . или обычной команды pip install:

{
  "mcpServers": {
    "usaspending": {
      "command": "python",
      "args": ["-m", "usaspending_gov_mcp.server"]
    }
  }
}

Перезапустите клиент — инструменты появятся.

Профили инструментов

При самостоятельном запуске по умолчанию используется USASPENDING_TOOL_PROFILE=full, который предоставляет все 55 инструментов. В готовых агентах для закупок используется профиль

USASPENDING_TOOL_PROFILE=acquisition-agent: он предоставляет стабильный набор из 20 инструментов для основных операций поиска контрактов, анализа расходов, работы с ведомствами и получателями, NAICS, PSC, транзакциями и субподрядами. Если указать неизвестный профиль, запуск будет остановлен с понятным сообщением об ошибке — каталог инструментов не изменится незаметно.

Примеры запросов

После настройки попробуйте следующие запросы:

• «Покажи 10 крупнейших контрактов NAVSEA, заключённых в FY2025, по сумме».

• «Найди все контракты NASA на разработку программного обеспечения с обоснованием закупки у единственного поставщика за последний год».

• «Какую сумму Leidos получил по федеральным контрактам и другим видам финансирования с 2020 года? Сгруппируй данные по финансовым годам».

• «Назови 15 крупнейших получателей контрактов DoD с ограничением участия для HUBZone».

• «Покажи полную историю изменений по PIID N00024-24-C-0085».

• «Сравни количество контрактов FFP и T&M на IT-услуги в Air Force за FY2024».

Примечания по проектированию

• Аутентификация не требуется. USAspending.gov предоставляет бесплатный публичный API.

• Группировка по финансовым периодам. Финансовый год длится с октября по сентябрь; первый квартал охватывает октябрь–декабрь, а первый месяц — октябрь. Для годовых результатов по финансовым годам new_awards_over_time суммирует данные источника по финансовым кварталам. Если выбранный диапазон дат охватывает только часть финансового года, результат включает данные только за эту часть, а не за весь год. Для кварталов и месяцев сохраняются исходные значения.

• Период охвата данных FFATA. spending_by_subaward_grouped ранжирует совокупные суммы сообщённых субподрядов для подходящих генеральных подрядчиков. Фильтры по датам не ограничивают эти суммы действиями по субподрядам в запрошенном периоде. Чтобы получить отчёт за конкретный период, передайте возвращённый award_generated_internal_id в search_subawards, получите все страницы результатов и отфильтруйте записи по action_date. В сообщаемых суммах могут повторяться накопительные значения; их сумма не равна новым расходам на субподряды.

• Диапазоны дат для контрактов. По умолчанию диапазон дат охватывает контракты, действовавшие в любой момент этого периода — от даты первоначального подписания до последнего действия. Поэтому совпадение не подтверждает, что действие произошло именно в выбранном диапазоне. Чтобы найти фактические действия, используйте spending_by_transaction, получите все страницы результатов и удалите дубликаты идентификаторов контрактов. Даты действий по отдельному контракту можно получить с помощью get_transactions. Параметр date_type="action_date" задаёт ограничение по дате последнего действия.

• Программы федеральных счетов. Списки программ содержат коды и названия за все опубликованные годы, но не включают суммы в долларах и не фильтруются по финансовому году. Инструмент самостоятельно получает страницы источника — не более 2 000 записей — и сообщает, полон ли список и был ли применён запрошенный FY. Для получения данных по ресурсам счёта за один год используйте числовой идентификатор счёта и снимок за соответствующий финансовый год. Итоги по программам ведомства относятся ко всему ведомству.

• Доступные финансовые годы. По умолчанию списки счетов относятся к последнему финансовому году, доступному в источнике. Проверяйте параметр fy, особенно после перехода на новый финансовый год в октябре. Если запрошенный год ещё не опубликован, в ответе будут указаны доступные годы. В данных о бюджетных ресурсах ведомства нет обязательного разделения на обязательные и дискреционные расходы.

• Нельзя объединять группы типов контрактов. Параметр award_type принимает одно из значений: contracts, idvs, grants, loans, direct_payments, other. Для разных категорий выполняйте отдельные вызовы.

• program_numbers применим только к финансовой помощи. Используйте его при значении award_type grants, loans, direct_payments или other. Для контрактов и IDV перечни финансовой помощи не предусмотрены, поэтому сервер возвращает соответствующее сообщение, а не нулевой результат.

• Понятные сообщения об ошибках. Типовые ошибки API — 422 для смешанных типов контрактов, 400 при отсутствии поля сортировки и 400 при пустом параметре keywords — преобразуются в рекомендации для вызывающей LLM.

• Автоматическая обработка поля сортировки. API USAspending требует, чтобы поле сортировки присутствовало в массиве полей. Сервер добавляет его автоматически.

• Разумные значения по умолчанию. По умолчанию поиск возвращает до 25 результатов; максимальное значение API — 100. Набор полей по умолчанию включает наиболее востребованные столбцы для каждой категории контрактов.

• Плоские параметры фильтрации. Большинство распространённых фильтров доступны в виде именованных параметров (keywords, awarding_agency, naics_codes и т. д.), а не вложенного словаря фильтров. Это упрощает обнаружение инструментов для LLM.

Источник данных

Все данные поступают с USAspending.gov, где объединяются сведения о контрактах из FPDS-NG, данные о финансовой помощи из FAADC и отчётность ведомств по DATA Act. Актуальность данных различается в зависимости от ведомства: сведения о контрактах, не связанных с DoD, обычно публикуются в течение 5 рабочих дней; для закупок DoD и USACE в FPDS действует 90-дневная задержка отчётности; данные о финансовой помощи становятся доступными в течение 2 дней после подачи.

Лицензия

MIT

Регрессионные тесты

Запустите PYTHONPATH=src uv run --python 3.12 python -m pytest -q из каталога этого пакета. Чтобы добавить проверки с обращением к публичному API, задайте USASPENDING_LIVE_TESTS=1 — ключ не требуется. Подробнее см. в файле testing.md.

Файл теста	Что проверяется
test_v0_3_features.py	Структура инструментов, фильтры и расширенные возможности API
test_density_r5.py	Регрессионные проверки граничных случаев и семантики
test_live_audit_r6.py	Проверка работающих конечных точек
test_live_audit_r7.py	Проверка параметров и пагинации на работающем API
test_content_fixes_1013.py	Исправления текста за октябрь: автономные проверки и проверки с обращением к API
test_round_8.py	Проверки свойств и валидации
test_entity_family_fixes.py	Семантика ведомств, получателей и контрактов
test_validation.py	Валидация входных данных
test_search_family_fixes.py	Семантика поиска и агрегирования
test_response_cache_hosted.py	Работа кэша в размещённой среде
test_audit_r11.py	Контрольные точки аудита с ограничением частоты запросов
test_throughput.py	Пропускная способность запросов и регулирование их частоты
test_tool_profiles.py	Выбор профилей инструментов
test_http.py	Обработка HTTP-запросов
test_content_e2e_1014.py	Сквозные регрессионные проверки рекомендаций по аудиту
test_published_scope_1015.py	Рекомендации по выбору инструментов в рамках опубликованных данных
test_new_awards_fiscal_year_1016.py	Проверка исправления годовых данных за финансовый год на сохранённых ответах и контроль неизменности выборок за кварталы и месяцы
test_subaward_period_scope_1017.py	Проверка охвата накопительных данных FFATA и полного получения отчётов с датами
test_federal_account_program_scope_1018.py	Проверка данных о программах за все годы на сохранённых ответах, полноты списка и получения финансовых данных за один год
test_federal_account_available_fy_1020.py	Проверка доступности данных источника за текущий финансовый год, получения данных за поддерживаемые годы и неизменности контрольного ответа 503
test_naics_current_retired_1021.py	Проверка фактически выведенных из употребления записей и действующих записей, не попавших в запрошенный лимит
test_award_date_overlap_r6.py	Проверка пересечения периода действия контракта с датами и полного получения датированных транзакций
test_sdk23_expected_guidance.py	Проверка понятных рекомендаций по восстановлению данных, отсутствия запросов к источнику до валидации, сохранения ответов источника и маскирования непредвиденных ошибок
Всего	2,322