USA Spending MCP

USA Spending MCP Server

Este é um servidor MCP HTTP streamable sem estado para interagir com USASPENDING.gov, a fonte oficial de dados de gastos do governo. Você pode acompanhar gastos governamentais ao longo do tempo, pesquisar gastos governamentais por agência, explorar gastos governamentais para comunidades e muito mais. O USASPENDING.gov fornece este prático dashboard que demonstra alguns dos poderes da API, caso você queira uma visão geral de alto nível do que pode ser alcançado com esta API. A documentação da API pode ser visualizada neste URL.

Executando Localmente

uv run src/server.py

Executando a partir do PyPi

uvx --from usaspending-mcp-server@latest usaspending-mcp-server

Executando a partir do Docker

docker build -t usaspending-mcp-server .
docker run -p 8000:8000 usaspending-mcp-server

Usando com Claude Desktop

Atualize seu claude_desktop_config.json com a seguinte configuração. Certifique-se de que o servidor MCP esteja em execução usando um dos métodos mencionados acima.

{
  "mcpServers": {
    "usaspending": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp"
      ]
    }
  }
}

Opções de Configuração

As seguintes variáveis de ambiente ou .env são aceitas para personalizar em qual host e porta o servidor MCP será executado.

MCP_SERVER_HOST
MCP_SERVER_PORT

Ferramentas

Nome	Descrição	Exemplos de prompts
federal_accounts	Use esta ferramenta para entender melhor como as agências recebem e gastam o financiamento congressional para executar seus programas, projetos e atividades.	- Forneça detalhes sobre como o Departamento de Segurança Interna gasta dinheiro.
list_budget_functions	Isso recupera uma lista de todas as Funções Orçamentárias ordenadas por título.	- Quanto o governo gasta em desenvolvimento comunitário e regional versus assuntos internacionais?
major_object_class	Estes dados podem ser usados para entender melhor as diferentes formas como uma agência específica gasta dinheiro.	- Quanto dinheiro o Departamento de Educação gasta com salários e benefícios dos funcionários?
recipient	Isso pode ser usado para visualizar os gastos governamentais relacionados a um destinatário específico. Isso retorna uma lista de destinatários, seu nível, DUNS, UEI e valor.	- Quais são algumas empresas que receberam financiamento da NSA?
spending	Estes dados podem ser usados para detalhar subconjuntos específicos de dados por nível de detalhamento. Esses dados representam todos os gastos governamentais no período especificado, agrupados pelo tipo de dados de sua escolha.	- Forneça gastos por agência para Ciência Geral, Espaço e Tecnologia.
spending_by_award	Isso permite filtragem complexa para subconjuntos específicos de dados de gastos. Aceita filtros e campos, e retorna os campos dos prêmios filtrados.	- Qual foi o maior prêmio em 2025? - Quais são algumas empresas que receberam grandes contratos federais no distrito de Lindsey Graham?
spending_over_time	Isso retorna uma lista de valores de prêmios agregados agrupados por período de tempo em ordem crescente (do mais antigo ao mais recente).	- Como os gastos com a Califórnia mudaram nos últimos 5 anos?
subawards	Isso retorna um conjunto filtrado de subpremiações.	- Descreva algumas das subpremiações para CONT_AWD_FA870221C0001_9700_-NONE-_-NONE- e forneça uma justificativa para elas.
total_budgetary_resources	Isso é usado para fornecer informações sobre os recursos orçamentários federais do governo.	- Qual foi o orçamento do governo em 2025 versus 2024? - Quanto dinheiro o governo federal fornece no total para várias agências governamentais?
toptier_agencies	Estes dados podem ser usados para entender melhor as diferentes formas como uma agência específica gasta dinheiro.	- Qual agência federal recebe mais dinheiro?

Explicação do diretório de ferramentas

Como cada ferramenta é basicamente um wrapper para uma rota de API, cada ferramenta é mapeada de forma semelhante à estrutura de diretórios no diretório api_contracts do usaspending-api. No entanto, para as ferramentas federal_accounts, recipient, spending e subawards, o mapeamento da API são os contratos mencionados no diretório raiz api_contracts/v2. Há um arquivo md para cada ferramenta, para que seja conveniente consultar a documentação usada para criar a ferramenta. Esses contratos raramente são atualizados no usaspending-api, mas verificações ainda devem ser realizadas para garantir que estejam atualizados. Atualmente, todos os contratos (também conhecidos como documentação da API) são referenciados a partir do commit dv551d0 do usaspending-api.

Testes

O MCP Inspector é uma boa forma de testar o esquema de entrada e saída sem conectar a um LLM. Há também um Cliente MCP de exemplo para testar o aplicativo usando OpenAI. Há também uma variedade de testes unitários focados nos manipuladores de ferramentas, esquemas de entrada/saída e chamadas HTTP para a API do USASpending. Eles podem ser executados com o seguinte comando.

uv run pytest

Contribuindo

Consulte a seção de testes como ponto de partida para testar suas alterações antes de enviar um PR. Se você estiver adicionando uma nova ferramenta, adicione também uma cópia do respectivo contrato usado como referência para criar o inputSchema e o outputSchema. Adicione a ferramenta no mesmo caminho em que ela existe no diretório de contatos do usaspending_api. Para a convenção de nomenclatura de arquivos, consulte o nome do arquivo de contrato e nomeie a ferramenta da mesma forma. Por exemplo, se você estiver criando uma ferramenta para a rota de API v2/disaster/spending_by_geography.md, essa ferramenta deve ser adicionada no caminho tools/v2/disaster/spending_by_geography.py e deve ser nomeada disaster_spending_by_geography. Caso haja alguma objeção a isso, por favor, explique no PR, pois não é infalível!

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.