sec-edgar-mcp

Un servidor MCP (Model Context Protocol) que ofrece acceso en lenguaje natural a las presentaciones de SEC EDGAR — búsqueda de empresas, contenido de presentaciones, cifras de estados financieros, transacciones de información privilegiada y comparaciones entre presentaciones — a través de HTTP en streaming, de modo que cualquier cliente MCP (Claude Code, Claude Desktop, etc.) pueda responder preguntas reales de investigación sobre presentaciones, basadas en presentaciones reales y no en conocimiento general.

Creado como pieza de portafolio que demuestra ingeniería orientada a producción alrededor de una API pública, con límite de tasa y sin autenticación: un limitador de tasa compartido de dos niveles, un caché de coalescencia, análisis sintáctico de HTML/XML validado con datos reales y una superficie de herramientas formada mediante pruebas con un cliente LLM real, no solo con pruebas unitarias. El razonamiento de diseño completo — y las compensaciones que implica — se encuentra en plans/architecture.md; los requisitos originales están en reference/product_spec.md.

Estado: funcionalmente completo hasta el Milestone 7 (las 6 herramientas, probadas con datos reales de EDGAR y un cliente MCP real). Aún no desplegado: este repositorio se ejecuta como servidor local hoy; el despliegue en contenedores es el Milestone 8.

Por qué HTTP y no stdio

SEC EDGAR requiere un User-Agent compatible con información de contacto y aplica un límite de tasa por IP (~10 req/s). Con stdio, el proceso local de cada usuario es su propia IP no coordinada: el límite de tasa nunca se ejerce ni se aplica realmente. Con HTTP, un despliegue significa una IP de salida, un presupuesto compartido y un solo lugar para hacer bien el cumplimiento, el límite de tasa y el caché. Esa decisión — y todo lo que implica (invariante de proceso único, backoff global 429, diseño de caché) — se detalla en la Decision 0 de plans/architecture.md.

Related MCP server: SEC EDGAR MCP

Herramientas

El docstring de cada herramienta es deliberadamente prescriptivo sobre cuándo llamarla y qué no cubre: consulta src/sec_edgar_mcp/server/tools.py. Las instructions de nivel superior del servidor (en src/sec_edgar_mcp/server/app.py) establecen el límite completo del alcance actual desde el principio, para que un cliente sepa qué está fuera del alcance antes de probar una herramienta, no después de un intento fallido.

Explícitamente fuera del alcance hoy (consulta reference/product_spec.md §7 para ver la lista completa y el motivo): compensación ejecutiva (tablas DEF 14A), secciones de prosa del 10-Q, como un MD&A trimestral, resumen por tipo de evento de los 8-K, búsqueda entre empresas / de texto completo y titularidad real superior al 5% (Schedule 13D/13G).

Inicio rápido

Requiere Python 3.14+ y uv.

uv sync

SEC EDGAR requiere un User-Agent compatible: el servidor falla rápidamente al inicio si no se proporciona uno, en lugar de fallar silenciosamente en la primera solicitud:

export SEC_EDGAR_USER_AGENT="your-app-name/0.1 (you@example.com)"

Ejecútalo:

uv run python -m sec_edgar_mcp

Inicia un servidor HTTP en streaming en 127.0.0.1:8000 (configurable mediante SEC_EDGAR_HOST / SEC_EDGAR_PORT; consulta src/sec_edgar_mcp/config.py para cualquier otro parámetro ajustable — límites de tasa, TTL de caché, reintentos/backoff — todos tienen valores predeterminados, solo se requiere el User-Agent).

Pruébalo con MCP Inspector

uv run mcp dev src/sec_edgar_mcp/__main__.py

Abre una interfaz de navegador para llamar a cada herramienta directamente con JSON-RPC sin procesar — útil para verificar la forma de entrada/salida de una herramienta individual, no para probar cómo un LLM selecciona realmente entre herramientas.

Conéctalo a Claude Code

Con el servidor en ejecución:

claude mcp add --transport http sec-edgar-mcp http://127.0.0.1:8000/mcp

Inicia una sesión nueva de claude (los servidores MCP se cargan al iniciar la sesión) y hazle una pregunta real — p. ej. "¿Ha cambiado el lenguaje de los factores de riesgo de Apple sobre la cadena de suministro en los dos últimos 10-K?" o "Muéstrame todas las ventas de información privilegiada (Form 4) de ejecutivos de Nvidia en los últimos 90 días, ordenadas por valor."

Desarrollo

uv run pytest          # unit + tool-layer tests (mocked EDGAR, no network)
uv run pytest -m live  # opt-in tests against real EDGAR
uv run ruff check .
uv run ruff format .
uv run mypy --strict src tests

Cuatro niveles de pruebas automatizadas, más una quinta manual — conectar el servidor en ejecución a un cliente MCP real y hacerle preguntas en lenguaje natural — que es lo que realmente encontró varios de los errores corregidos en la historia de este repositorio (consulta la sección Testing de plans/architecture.md y los mensajes de commit recientes para más detalles). tests/fixtures/filings/ contiene ~10 presentaciones reales de 10-K y Form 4, consolidadas, de distintos tamaños de declarantes y épocas: los analizadores se validan con datos reales, no con HTML sintético.

Estructura del proyecto

src/sec_edgar_mcp/
  config.py        # required SEC_EDGAR_USER_AGENT, everything else defaulted
  domain/           # Pydantic models (CIK, Filing, InsiderTransaction, FinancialFact, ...)
  edgar/            # rate limiter, cache, HTTP client, endpoint wrappers, parsers
  services/         # composition logic (resolve, compare, insiders, financials)
  server/           # MCPServer, @mcp.tool() adapters, logging, scope instructions
tests/
  fixtures/filings/ # ~10 real, committed SEC filings
plans/architecture.md    # full design reasoning and milestone history
reference/product_spec.md # original requirements + recorded scope decisions