us-gov-data-mcp

Un servidor MCP para datos del gobierno de EE. UU. Pregunta a tu asistente de IA qué contratos federales están por expirar, o qué empresas públicas tuvieron más ingresos el año pasado — y obtén respuestas que puedes verificar contra los propios registros del gobierno.

Construido sobre la API USAspending del Tesoro de EE. UU. y los datos EDGAR XBRL de la SEC. Sin scraping, sin clave de API, sin cuenta, sin datos personales.

Por qué existe esto

Ambas fuentes publican todo y permiten consultar casi nada.

usaspending.gov no permite buscar por fecha de fin de contrato. Pero cuando termina el periodo de ejecución de un contrato federal, el trabajo normalmente tiene que volver a licitarse — y esas relicitaciones son las oportunidades de mayor probabilidad en la contratación pública, visibles en datos públicos meses antes de que aparezca cualquier solicitud.

sec.gov sirve los informes de una empresa a la vez. No hay forma en el sitio de preguntar qué empresas públicas tuvieron ingresos superiores a 100 mil millones de dólares, o cuáles tienen más efectivo. La API frames de la SEC puede responder eso para los ~5.800 declarantes en una sola llamada, si ya conoces la etiqueta XBRL y el formato del periodo.

Este servidor responde a las preguntas que esos sitios no pueden.

Related MCP server: sec-edgar-mcp

Cuatro herramientas

find_expiring_contracts — relicitaciones

Contratos federales próximos a relicitarse, con el adjudicatario actual y los días restantes. expiring_after_days establece tu tiempo de preparación de la oferta, porque un contrato que termina la semana que viene es inútil para prepararse.

{
  "days_until_expiry": 120,
  "recipient": "PERATON ENTERPRISE SOLUTIONS LLC",
  "amount_usd": 682369225.00,
  "awarding_agency": "General Services Administration",
  "verify_url": "https://www.usaspending.gov/award/..."
}

search_federal_contracts

Contratos adjudicados por agencia, palabra clave, fecha o importe en dólares. Quién se está adjudicando el trabajo federal, en qué gasta una agencia, el historial de un competidor.

screen_public_companies

Clasifica todas las empresas públicas de EE. UU. por cualquier métrica financiera declarada.

"¿Qué empresas tuvieron ingresos superiores a 200 mil millones de dólares en 2023?"

{ "company": "Walmart Inc.", "value": 648125000000, "unit": "USD",
  "period_end": "2023-12-31", "period_type": "annual",
  "verify_url": "https://www.sec.gov/Archives/edgar/data/104169/..." }

company_financial_history

El historial declarado de una empresa para una métrica — ingresos, beneficio neto, activos, flujo de caja — deduplicado, con el tipo de formulario y la fecha de presentación en cada registro.

Todo es verificable

Cada registro lleva un verify_url al documento gubernamental del que procede. Ábrelo y compara.

Eso importa sobre todo con una IA en el circuito: cuando un asistente informa de una cifra en dólares, deberías poder comprobarla contra la fuente en lugar de confiar en la cadena. Si un valor discrepa alguna vez del registro oficial, eso es un error — por favor, abre un issue.

Tres trampas que esto maneja por ti

Los datos brutos de la SEC inducen a error de tres formas concretas, cada una silenciosa — obtienes un número erróneo plausible, no un error.

1. Un 10-Q informa del trimestre y del acumulado anual con la misma fecha de fin. Comparar el beneficio neto entre informes mezcla silenciosamente una cifra de tres meses con una de nueve. Cada registro lleva period_type, y puedes filtrar por él.

2. El mismo dato se repite en varios informes con valores diferentes. El 10-K de este año reexpresa las cifras del año pasado. Deduplicado a un registro por periodo, ganando la presentación más reciente — el propio tratamiento de las reexpresiones por parte de la SEC.

3. Las empresas cambian de etiquetas XBRL con el tiempo. Microsoft presentó Revenues hasta 2010 y una etiqueta diferente después. Tomar la primera etiqueta que devuelve datos produce un historial parcial desactualizado; esto fusiona todas ellas.

Instalación

uvx --from git+https://github.com/groundtruthtools/us-gov-data-mcp us-gov-data-mcp

Claude Desktop — añade a claude_desktop_config.json:

{
  "mcpServers": {
    "us-gov-data": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/groundtruthtools/us-gov-data-mcp",
        "us-gov-data-mcp"
      ],
      "env": { "SEC_USER_AGENT": "Your Name your@email.com" }
    }
  }
}

Funciona con cualquier cliente MCP: Claude Desktop, Claude Code, Cursor, VS Code.

Vale la pena configurar SEC_USER_AGENT. La política de acceso justo de la SEC exige un User-Agent que contenga una dirección de contacto, y las solicitudes sin uno reciben un 403. Se incluye un valor por defecto para que las herramientas funcionen sin configuración, pero identificarte es lo correcto y te mantiene fuera de una identidad compartida.

Una peculiaridad, aprendida por las malas: no pongas una URL en esa cadena. La SEC devuelve 403 para cualquier User-Agent que contenga una. Tu Nombre tu@email.com funciona; añadir github.com/... no.

Todavía no está en PyPI, así que instala desde el repositorio. Cuando llegue allí, esto se convierte en un simple uvx us-gov-data-mcp.

Límites honestos

• Contratos: adjudicados, no solicitudes abiertas. Para licitaciones publicadas, usa SAM.gov.

• Contratos: solo federales, sin datos anteriores al año fiscal 2008.

• La búsqueda de relicitaciones cubre contratos con actividad en el último año, porque USAspending limita la profundidad de paginación de los resultados. Un contrato inactivo durante mucho tiempo puede no aparecer, y una búsqueda demasiado amplia lo dice en lugar de devolver una lista vacía con falsa seguridad.

• SEC: la cobertura XBRL comienza alrededor de 2009, y solo cubre conceptos que las empresas etiquetaron realmente. Los declarantes más pequeños etiquetan menos.

• Informa; no calcula. Sin ratios, tasas de crecimiento ni métricas derivadas — eso sería nuestra aritmética, no la presentación, y no podrías verificarlo contra la fuente.

• No es asesoramiento de inversión. Es una herramienta de reformateo de datos.

También en Apify

La misma lógica funciona como herramientas alojadas, sin necesidad de instalación:

• US Federal Contract Awards & Recompete Finder

• SEC EDGAR Financial Data & Company Screener

Fuentes de datos y licencia

Contratos: USAspending.gov, Departamento del Tesoro de EE. UU., publicado bajo la DATA Act. Datos financieros: SEC EDGAR, Comisión de Bolsa y Valores de EE. UU. Ambos de dominio público. Código: MIT.