USA Spending MCP

Servidor MCP de USA Spending

Este es un servidor MCP HTTP de transmisión sin estado para interactuar con USASPENDING.gov, la fuente oficial de datos de gasto gubernamental. Puedes rastrear el gasto gubernamental a lo largo del tiempo, buscar gasto gubernamental por agencia, explorar el gasto gubernamental hacia comunidades, y mucho más. USASPENDING.gov proporciona este práctico panel que muestra algunos de los poderes de la API si deseas una visión general de alto nivel de lo que puedes lograr con esta API. La documentación de la API se puede consultar en esta URL.

Ejecución Local

uv run src/server.py

Ejecución desde PyPi

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

Ejecución desde Docker

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

Uso con Claude Desktop

Actualiza tu claude_desktop_config.json con la siguiente configuración. Asegúrate de que el servidor MCP esté ejecutándose utilizando uno de los métodos mencionados anteriormente.

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

Opciones de Configuración

Se aceptan las siguientes variables de entorno o de .env para personalizar el host y el puerto en los que se ejecuta el servidor MCP.

MCP_SERVER_HOST
MCP_SERVER_PORT

Herramientas

Nombre	Descripción	Ejemplos de indicaciones
federal_accounts	Utiliza esta herramienta para comprender mejor cómo las agencias reciben y gastan la financiación del Congreso para llevar a cabo sus programas, proyectos y actividades.	- Proporciona detalles específicos sobre cómo el Departamento de Seguridad Nacional gasta dinero.
list_budget_functions	Esto recupera una lista de todas las Funciones Presupuestarias ordenadas por su título.	- ¿Cuánto gasta el gobierno en desarrollo comunitario y regional en comparación con asuntos internacionales?
major_object_class	Estos datos se pueden utilizar para comprender mejor las diferentes formas en que una agencia específica gasta dinero.	- ¿Cuánto dinero gasta el Departamento de Educación en salarios y beneficios de empleados?
recipient	Esto se puede utilizar para visualizar el gasto gubernamental relacionado con un destinatario específico. Esto devuelve una lista de destinatarios, su nivel, DUNS, UEI y monto.	- ¿Cuáles son algunas empresas que recibieron financiación de la NSA?
spending	Estos datos se pueden utilizar para profundizar en subconjuntos específicos de datos según el nivel de detalle. Estos datos representan todo el gasto gubernamental en el período de tiempo especificado, agrupado por el tipo de datos de tu elección.	- Proporciona el gasto por agencia para Ciencia General, Espacio y Tecnología.
spending_by_award	Esto permite un filtrado complejo para subconjuntos específicos de datos de gasto. Acepta filtros y campos, y devuelve los campos de las adjudicaciones filtradas.	- ¿Cuál fue la adjudicación más grande en 2025? - ¿Cuáles son algunas empresas que recibieron contratos federales importantes en el distrito de Lindsey Graham?
spending_over_time	Esto devuelve una lista de montos de adjudicaciones agregados agrupados por período de tiempo en orden ascendente (del más antiguo al más reciente).	- ¿Cómo ha cambiado el gasto hacia California en los últimos 5 años?
subawards	Esto devuelve un conjunto filtrado de subadjudicaciones.	- Describe algunas de las subadjudicaciones para CONT_AWD_FA870221C0001_9700_-NONE-_-NONE- y proporciona una justificación para ellas.
total_budgetary_resources	Esto se utiliza para proporcionar información sobre los recursos presupuestarios federales del gobierno.	- ¿Cuál fue el presupuesto del gobierno en 2025 en comparación con 2024? - ¿Cuánto dinero proporciona el gobierno federal en total a varias agencias gubernamentales?
toptier_agencies	Estos datos se pueden utilizar para comprender mejor las diferentes formas en que una agencia específica gasta dinero.	- ¿Qué agencia federal recibe la mayor cantidad de dinero?

Explicación del directorio de herramientas

Como cada herramienta es básicamente un envoltorio para una ruta de API, cada herramienta se mapea de manera similar a la estructura de directorios en el directorio api_contracts de usaspending-api. Sin embargo, para las herramientas federal_accounts, recipient, spending y subawards, su mapeo de API son los contratos mencionados en el directorio raíz api_contracts/v2. Hay un archivo md para cada herramienta, por lo que es conveniente consultar la documentación utilizada para crear la herramienta. Estos contratos rara vez se actualizan en usaspending-api, pero aún así se deben realizar verificaciones para asegurarse de que estén actualizados. Actualmente, todos los contratos (también conocidos como documentación de API) se referencian desde el commit dv551d0 de usaspending-api.

Pruebas

MCP Inspector es una buena forma de probar el esquema de entrada y salida sin conectarse a un LLM. También hay un Cliente MCP de muestra para probar la aplicación usando OpenAI. También hay una variedad de pruebas unitarias centradas en los manejadores de herramientas, esquemas de entrada/salida y llamadas HTTP a la API de USASpending. Se pueden ejecutar con el siguiente comando.

uv run pytest

Contribuciones

Consulta la sección de pruebas como punto de partida para probar tus cambios antes de enviar un PR. Si estás agregando una nueva herramienta, agrega también una copia del contrato respectivo utilizado como referencia para crear el inputSchema y outputSchema. Agrega la herramienta en la misma ruta en la que existe en el directorio de contactos de usaspending_api. Para la convención de nombres de archivos, consulta el nombre del archivo de contrato y nombra la herramienta de la misma manera. Por ejemplo, si estás creando una herramienta para la ruta de API v2/disaster/spending_by_geography.md, esta herramienta debe agregarse en la ruta tools/v2/disaster/spending_by_geography.py y la herramienta debe llamarse disaster_spending_by_geography. Si hay alguna objeción a esto, explica el motivo en el PR, ¡ya que no es infalible!

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulta el archivo LICENSE para más detalles.