secedgar-mcp-server

Archivos SEC EDGAR y datos financieros

GitHub
10
Prueba este MCPPatrocinado

Documentación

@cyanheads/secedgar-mcp-server

Consulta presentaciones de SEC EDGAR, datos financieros XBRL e información de empresas a través de MCP. STDIO y HTTP Streamable.

16 herramientas (+1 opcional) • 2 recursos • 1 indicación

npm License Docker MCP SDK TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework

Servidor público alojado: https://secedgar.caseyjhand.com/mcp

Herramientas

Catorce herramientas para consultar datos de SEC EDGAR, más tres para análisis SQL sobre los dataframes de canvas respaldados por DuckDB que esas herramientas materializan:

HerramientaDescripción
secedgar_company_searchEncuentra empresas y recupera información de entidades con presentaciones recientes opcionales
secedgar_search_filingsBusca presentaciones de EDGAR desde 1993 — texto completo (2001+) más navegación respaldada por archivos para rangos anteriores a 2001
secedgar_get_filingObtiene los metadatos y el contenido documental de una presentación específica
secedgar_get_financialsObtiene datos financieros históricos XBRL de una empresa
secedgar_get_snapshotPerfil financiero en una sola llamada: el valor más reciente de cada concepto compatible, agrupado por estado financiero
secedgar_get_material_eventsPresentaciones 8-K con códigos de ítems decodificados y filtrables: ganancias, cambios de directivos, no confiabilidad
secedgar_get_insider_transactionsTransacciones de información privilegiada del Formulario 4 / 4-A (compras, ventas, donaciones, concesiones, ejercicios) analizadas desde XML de propiedad
secedgar_get_institutional_holdingsTenencias institucionales trimestrales 13F-HR analizadas desde la tabla de información
secedgar_find_holdersBúsqueda inversa de 13F: qué gestores institucionales informaron tener un emisor
secedgar_get_beneficial_ownersTenedores de bloque del 5%+ de un emisor, analizados desde presentaciones estructuradas SCHEDULE 13D / 13G
secedgar_get_fund_holdingsCarteras de fondos cotizados y fondos mutuos del informe trimestral NPORT-P
secedgar_fetch_framesObtiene marcos XBRL de SEC para un concepto × un período en todas las empresas que informan
secedgar_compare_companiesCompara empresas nombradas en varios conceptos, alineadas en períodos de calendario
secedgar_search_conceptsDescubre nombres de conceptos XBRL compatibles o búsqueda inversa de una etiqueta cruda
secedgar_dataframe_describeLista dataframes de canvas con procedencia, TTL y esquema
secedgar_dataframe_queryEjecuta un SELECT de una sola declaración en los dataframes
secedgar_dataframe_dropElimina un dataframe de canvas por nombre. Opcional mediante EDGAR_DATAFRAME_DROP_ENABLED=true — desactivado por defecto ya que el TTL ya gestiona la limpieza, e inutilizable hasta que se establezca la bandera

secedgar_company_search

Punto de entrada para la mayoría de los flujos de trabajo de EDGAR: resuelve tickers, nombres o CIKs a detalles de entidad.

  • Admite símbolos de ticker (AAPL, VOO), nombres de empresa (Apple) o números CIK (320193); un ticker de acción de clase múltiple se resuelve en cualquiera de las dos formas (BRK-B o BRK.B)
  • Los fondos cotizados y fondos mutuos se resuelven por ticker mediante company_tickers_mf.json; los resultados de fondos incluyen series_id y class_id para el alcance posterior
  • Tanto los nombres actuales como los anteriores de la empresa se resuelven (Facebook → Meta Platforms, Square → Block)
  • La forma del sufijo corporativo no tiene que coincidir con el registro (Beacon Financial Corporation → Beacon Financial Corp); Corp, Inc, Co y Ltd permanecen distintos entre sí, ya que los registrantes separados difieren solo por cuál usan (TORO CO vs TORO CORP.)
  • Sugerencias de coincidencia cercana en una búsqueda de nombre o ticker con cero resultados (p. ej., Microsfot → MICROSOFT CORP / MSFT, CSWI → CSW INDUSTRIALS, INC. / CSW)
  • Opcionalmente incluye presentaciones recientes con filtrado por tipo de formulario
  • El filtrado por fecha (filed_after / filed_before) y los filtros de formulario con poca cobertura paginan en el archivo de presentaciones más antiguas, alcanzando presentaciones que preceden a la ventana reciente de ~1000 entradas (p. ej., un 10-K de 2005); history_scanned_through revela la profundidad del escaneo, y el historial completo filtrado se materializa como un dataframe df_<id> cuando supera el filing_limit en línea
  • Devuelve metadatos de entidad: código SIC, bolsas, fin de año fiscal, estado de incorporación

secedgar_search_filings

Busca presentaciones de EDGAR desde 1993. La búsqueda de texto completo cubre 2001-presente (el piso del índice EFTS); los rangos de fecha anteriores a 2001 se sirven desde los archivos: la coincidencia de texto completo anterior a 2001 requiere alcance de entidad.

  • Frases exactas ("material weakness"), operadores booleanos (revenue OR income), comodines (account*)
  • Segmentación de entidad dentro de la cadena de consulta (cik:320193 o ticker:AAPL) — con alcance del lado del servidor por CIK, por lo que se incluyen presentaciones realizadas bajo un nombre anterior de la empresa (mismo CIK); un ticker de acción de clase múltiple se resuelve en cualquiera de las dos formas (ticker:BRK-B o ticker:BRK.B)
  • Modo de navegación: omite query para listar presentaciones por tipo de formulario (forms=["S-1"]) y/o entidad (ticker:/cik:), opcionalmente limitado por fecha: un rango de fecha desnudo no es una búsqueda válida y debe combinarse con formularios o segmentación de entidad
  • Los rangos de fecha anteriores a 2001 (hasta 1993) se enrutan a los archivos: un rango con alcance de entidad lee el historial completo de presentaciones del declarante; un rango de formularios/fecha sin alcance navega por el índice completo trimestral. Cada fila lleva un campo source (efts / submissions / full-index), preservado en el dataframe df_<id>
  • El texto libre anterior a 2001 se compara leyendo documentos, por lo que necesita alcance ticker:/cik: para acotar el trabajo: el pre-filtro de formulario + fecha selecciona candidatos, se leen hasta 50, y scan informa candidatos / escaneados / coincidentes en lugar de presentar una lectura parcial como completa. La tasa de solicitudes de SEC es el costo: aproximadamente 5s para un escaneo completo de 50 documentos. Cada lectura cubre todo el .txt de accession (las presentaciones anteriores a 1997 no exponen URL por documento), por lo que una coincidencia puede estar en un anexo adjunto en lugar del cuerpo del formulario solicitado
  • Un rango que cruza 2001-01-01 se divide en el límite y se fusiona: el índice de texto completo sirve desde 2001 en adelante, los archivos sirven el resto. period_ending, ticker, file_description, sic y location existen solo en filas source: efts, por lo que un resultado fusionado los lleva en algunas filas y no en otras
  • Filtrado por rango de fecha, filtrado por tipo de formulario, paginación hasta 10,000 resultados
  • Devuelve distribución de formularios para búsquedas de seguimiento más específicas
  • Cuando la ventana con alcance de entidad excede el límite en línea, la ventana EFTS ya obtenida se materializa como un dataframe df_<id> — consúltalo con secedgar_dataframe_query

secedgar_get_filing

Obtiene los metadatos y el contenido documental de una presentación específica por número de accession.

  • Acepta números de accession en formato con guiones o sin guiones
  • Convierte presentaciones HTML a texto plano legible
  • Límite de contenido configurable (1K–200K caracteres, 50K por defecto)
  • Puede obtener anexos específicos por nombre de documento
  • Entradas binarias — páginas escaneadas, anexos PDF, archivos empaquetados y hojas de cálculo — se marcan como binary en el catálogo de documentos y se rechazan con un error binary_document en lugar de devolverse como bytes decodificados
  • Paginación por desplazamiento para documentos grandes (10-K, S-1/A pueden superar 1M de caracteres): pasa next_offset de una respuesta truncada como offset en la siguiente llamada para continuar leyendo; las respuestas truncadas de primera página incluyen un outline detectado (encabezados con desplazamientos) para navegación dirigida
  • Segmentación de secciones mediante el parámetro section: salta directamente a un encabezado nombrado por coincidencia de subcadena que ignora mayúsculas/minúsculas, estilo de espacios en blanco y estilo de comillas (p. ej., "risk factors", "item 7", "certain relationships"), por lo que un encabezado copiado del esquema se resuelve ya sea que lleve los espacios no separables y comillas curvas de la presentación o los planos; en caso de no coincidencia, el error lleva el esquema detectado para que puedas elegir el encabezado correcto
  • El texto extraído se almacena en caché por accession + document (LRU acotado, 8 entradas), lo que hace que las llamadas paginadas posteriores sean económicas

secedgar_get_financials

Obtiene datos financieros históricos XBRL de una empresa con resolución de nombres de concepto amigables.

  • Nombres amigables como "revenue", "net_income", "eps_diluted" se resuelven automáticamente a etiquetas XBRL correctas
  • Maneja cambios históricos de etiquetas (p. ej., reconocimiento de ingresos ASC 606)
  • Deduplicación automática a un valor por período de calendario estándar
  • Filtra por períodos anuales, trimestrales o todos
  • limit opcional limita la serie en línea a los N períodos más recientes; la serie completa permanece consultable mediante el dataframe df_<id>
  • Los resultados trimestrales llevan una entrada caveats que nombra cada trimestre de calendario ausente de la serie etiquetada por marco: SEC informa el cuarto trimestre fiscal como el residual del 10-K, por lo que el trimestre de calendario que abarca el cuarto trimestre fiscal no tiene un valor trimestral discreto (incluidos los declarantes de año calendario), y un declarante cuyos otros trimestres fiscales abarcan duraciones no calendarias pierde un segundo trimestre de la misma manera
  • Una entrada adicional caveats cuando el concepto se resolvió a una etiqueta XBRL que SEC ha retirado de la taxonomía — eso solo ocurre cuando ninguna etiqueta actual informa para el declarante, y la serie puede detenerse años antes
  • Consulta el recurso secedgar://concepts para el mapeo completo

secedgar_get_snapshot

Construye un perfil financiero de empresa en una sola llamada en lugar de una serie de llamadas secedgar_get_financials.

  • Lee la carga útil completa de companyfacts del declarante una vez, luego resuelve cada concepto compatible contra ella
  • Misma deduplicación de marcos y prioridad de etiquetas que secedgar_get_financials, por lo que ambos coinciden para cualquier concepto que cubran
  • Los conceptos de duración (estado de resultados, flujo de caja, por acción) informan su último año completo y su último trimestre individual; los conceptos de balance general e información de entidad informan su último valor puntual
  • Los conceptos que el declarante no informa se listan bajo gaps con las etiquetas XBRL que se intentaron — nunca se rellenan con ceros ni se interpolan
  • Los declarantes IFRS se resuelven a través de las variantes de etiquetas IFRS mapeadas mediante taxonomy: "ifrs-full", que cubre el estado de resultados, balance general, flujo de caja y conceptos por acción; cada línea informa la taxonomía de la que proviene su valor
  • Perfil compacto de un solo registro — sin dataframe; recurre a secedgar_get_financials cuando necesites una serie temporal

secedgar_get_insider_transactions

Superficie la actividad de información privilegiada del Formulario 4 / 4-A de una empresa analizando XML de propiedad. Las declaraciones iniciales del Formulario 3 y las declaraciones anuales del Formulario 5 no están cubiertas — accede a ellas con secedgar_search_filings (forms: ["3", "5"]) más secedgar_get_filing.

  • Persona que informa, relación con el emisor (director, ejecutivo + título, propietario del 10%) y fecha de transacción
  • Código de transacción mapeado a un tipo legible (compra, venta, donación, concesión, ejercicio, …); acciones firmadas por adquiridas/enajenadas
  • Precio por acción y acciones poseídas después de cada transacción; cubre líneas no derivadas (mercado abierto) y derivadas (opciones/RSU)
  • Filtra por transaction_type (purchase, sale, all); escanea las presentaciones más recientes primero
  • El conjunto completo de transacciones analizadas de las presentaciones recientes escaneadas se materializa como un dataframe df_<id> (la lista en línea es una vista previa limitada a limit) — consúltalo con secedgar_dataframe_query para agregar compras/ventas netas por información privilegiada

secedgar_get_institutional_holdings

Superficie las tenencias institucionales trimestrales 13F-HR analizando la tabla de información.

  • Pase el filador institucional (CIK o nombre legal completo, p. ej. 0000102909 para Vanguard) para ver qué posee; para la dirección inversa — qué gestores poseen una empresa determinada — use secedgar_find_holders, cuyos resultados de filer_cik alimentan directamente esta herramienta
  • Cada tenencia: nombre del emisor, CUSIP, valor de mercado (USD enteros), acciones/principal y put/call; las filas sin procesar también incluyen la discreción de inversión
  • Las sublíneas para el mismo valor (una por gestor/cuenta) se consolidan en posiciones distintas ordenadas por valor de forma predeterminada — pase consolidate: false para las filas de presentación sin procesar
  • Resuelve el nombre del gestor que presenta y el trimestre de reporte desde la portada; apunte a un trimestre específico con quarter (p. ej. "2025-Q4")
  • total_holdings_in_filing cuenta las filas sin procesar de la tabla de información; total_positions cuenta las posiciones distintas después de la consolidación (ambos antes de limit)
  • Pagine a través de una tabla de información grande con offset — la respuesta repite el offset efectivo y devuelve next_offset mientras queden filas, de modo que cada posición siga siendo accesible incluso cuando el lienzo está deshabilitado
  • El conjunto completo de tenencias analizadas se materializa como un dataframe de df_<id> (la lista en línea es una página de limit filas) — consúltelo con secedgar_dataframe_query para agregaciones de presentación completa o uniones entre trimestres en cusip + reporting_period

secedgar_find_holders

Búsqueda inversa de 13F: qué gestores institucionales reportaron una posición en un emisor, para un trimestre de reporte.

  • Buscar por cusip coincide con el identificador que la propia tabla de información del 13F lleva — la ruta precisa. Louisiana-Pacific Q1 2026 devuelve 451 presentaciones por CUSIP 546347105 frente a 43 por la frase "LOUISIANA-PACIFIC CORP"; la ruta por nombre tanto sub-coincide (los gestores escriben el nombre de manera diferente) como sobre-coincide (un emisor no relacionado que comparte una palabra)
  • Un CUSIP no se puede derivar de un ticker en ningún lugar de EDGAR — léalo de cualquier resultado de secedgar_get_institutional_holdings, o recurra a la ruta por nombre
  • quarter apunta a un período de reporte ("2026-Q1"); omítalo para el trimestre más reciente cuyo plazo de presentación de 45 días haya pasado. El trimestre aplicado y su ventana de presentación se repiten
  • Las presentaciones se mantienen por el período que reportan, no por la fecha en que se presentaron, por lo que las enmiendas que reexpresan un trimestre anterior (aproximadamente el 6% de cualquier ventana) no caen en la lista de tenedores del trimestre equivocado
  • Se obtienen hasta 500 filas de filadores por llamada; total_filings reporta el recuento completo y dataset.truncated señala cuando existen más
  • La lista no está clasificada. La relevancia de búsqueda de EDGAR no lleva ninguna señal sobre el tamaño de la posición — lea la posición real de un gestor pasando su filer_cik a secedgar_get_institutional_holdings

secedgar_get_beneficial_owners

Las participaciones del 5% o más en un emisor — la capa de accionistas de bloqueo entre los iniciados del Formulario 4 y los portafolios 13F. La entrada es el emisor, la empresa que está siendo poseída.

  • 13D es el formulario activista y lleva el propósito declarado del filador de la transacción; 13G es el formulario pasivo y no tiene ningún elemento de propósito, que es la diferencia sustantiva entre una participación que pretende influir en el control y una que no. Filtre con form_kind
  • Cada persona que reporta se lista por separado. El poder de voto, el poder dispositivo y el porcentaje de la clase se reportan por persona incluso en una presentación conjunta donde varios fondos y su principal controlador reportan las mismas acciones subyacentes — sumar esos porcentajes cuenta doblemente la posición
  • La cobertura comienza 2024-12-18, cuando la SEC reemplazó las presentaciones de texto heredadas SC 13D / SC 13G con XML estructurado bajo los nombres actuales SCHEDULE 13D / SCHEDULE 13G. Las participaciones anteriores son legibles pero no analizables, y legacy_filings_before_coverage reporta cuántas tiene el emisor — acceda a ellas con secedgar_search_filings y léalas con secedgar_get_filing
  • Las enmiendas llevan la posición actual y se incluyen de forma predeterminada; include_amendments=false deja solo las presentaciones que abrieron una posición
  • El conjunto completo analizado se registra como un dataframe de df_<id> con una fila por persona que reporta, por lo que se une a los dataframes de iniciados y 13F en el CIK del emisor

secedgar_get_fund_holdings

Lo que posee un ETF o fondo mutuo, del informe de portafolio NPORT-P que presenta cada trimestre — el inverso de las herramientas de propiedad, que responden quién posee una empresa.

  • La entrada es el fondo: un ticker (VOO), un ID de serie de fondos de la SEC (S000002839) o un CIK. Los fideicomisos de fondos se indexan por ticker y serie en lugar de por nombre, así que nombre al registrante por CIK a menos que el fondo mismo cotice bajo ese nombre (SPDR S&P 500 ETF Trust)
  • Un NPORT-P cubre exactamente una serie de fondos y un fideicomiso registrante presenta un informe por serie por período, por lo que un fideicomiso que gestiona varios fondos necesita que se nombre el fondo específico. Un registrante que se resuelve a más de una serie devuelve las series listadas, cada una con su ticker; uno cuyas series no llevan ticker se enruta leyendo la serie de su informe más reciente, porque el historial de presentaciones de un fideicomiso intercala fondos cuyos trimestres fiscales terminan en meses diferentes
  • Cada resultado está fechado en report_period_date. Los informes se publican aproximadamente dos meses después del período que cubren, por lo que las tenencias son el portafolio a esa fecha, no a hoy; publication_lag_days indica la brecha. Apunte a un período anterior con report_date, elegido de los available_report_periods en cualquier respuesta
  • Las posiciones llevan el nombre del valor, CUSIP/ISIN/LEI donde el filador los reporta, saldo de acciones, valor en USD y porcentaje de activos netos, junto con activos netos a nivel de fondo, activos totales y pasivos totales
  • Las posiciones vienen primero las más grandes por porcentaje de activos netos, una página de limit filas de offset. Un fondo indexado amplio reporta miles — el informe más reciente de Vanguard Total Stock Market lleva 3,524 — por lo que el informe completo se registra como un dataframe de df_<id> para agregación y para unir los dataframes de 13F e iniciados en CUSIP

secedgar_get_material_events

El historial de 8-K de una empresa con códigos de ítems decodificados y filtrables — la única superficie que puede delimitar por lo que el evento realmente fue en lugar de por formulario.

  • Filtre con items (p. ej. ["2.02"] para resultados de operaciones, ["5.02"] para salidas de oficiales, ["4.02"] para no confiabilidad); secedgar_search_filings y secedgar_company_search no pueden ver ítems en absoluto
  • Dos regímenes de numeración son aceptados y decodificados: el esquema punteado en vigor desde 2004-08-23, y los enteros simples anteriores (el 12 heredado es el ancestro de 2.02, 9 de 7.01). La decodificación se basa en la forma del código, por lo que una presentación que cruza el cambio nunca se decodifica mal, y una ventana que lo abarca necesita ambos códigos en el filtro
  • item_distribution cuenta cada código en la ventana escaneada antes del filtro, por lo que un filtro con cero coincidencias devuelve los ítems que sí están presentes en lugar de un callejón sin salida
  • Una ventana de fechas pagina en el archivo de presentaciones más antiguas, alcanzando presentaciones 8-K que preceden a la ventana reciente de ~1000 presentaciones; history_scanned_through revela la profundidad del escaneo
  • La tabla de decodificación completa está en el recurso secedgar://filing-types
  • El conjunto filtrado completo se materializa como un dataframe de df_<id> con códigos de ítems en cada fila — la frecuencia de ítems a lo largo del tiempo está a un secedgar_dataframe_query de distancia

secedgar_fetch_frames

Obtenga marcos XBRL de la SEC para un concepto × un período en todas las empresas que reportan.

  • Mismos nombres de conceptos amigables que secedgar_get_financials
  • Admite períodos anuales (CY2023), trimestrales (CY2024Q2) e instantáneos (CY2023Q4I)
  • La respuesta en línea devuelve una página de las empresas clasificadas (orden + límite), con enriquecimiento de ticker
  • Avance más abajo en la clasificación con offset — la respuesta repite el offset efectivo y devuelve next_offset mientras queden empresas, por lo que los rangos más allá de la primera página siguen siendo accesibles incluso cuando el lienzo está deshabilitado
  • La respuesta completa de marcos (todos los que reportan, típicamente 2k–10k filas) se materializa como un dataframe de df_<id> — consúltelo con secedgar_dataframe_query
  • related_tags señala etiquetas de definición alternativa que algunos filadores usan como su línea principal (p. ej. cash → total inclusivo de efectivo restringido, equity → total inclusivo de NCI), por lo que un cribado de universo completo en la etiqueta base no es silenciosamente sub-inclusivo — consulte esas por separado

secedgar_compare_companies

Compare 2-10 empresas nombradas en 1-8 conceptos, alineados en períodos de calendario — la forma intermedia entre secedgar_get_financials (una empresa a lo largo del tiempo) y secedgar_fetch_frames (un período en todo el mercado).

  • Una lectura de companyfacts por empresa, resuelta a través de la misma deduplicación de marcos y prioridad de etiquetas que secedgar_get_financials
  • Los conceptos de balance general e información de entidad se alinean en el año o trimestre de calendario en el que cae su instantánea puntual, por lo que se sientan en la misma matriz que las líneas del estado de resultados; cada celda mantiene su marco XBRL subyacente
  • periods limita la matriz en línea (1-12, predeterminado 4) y la ventana se reduce aún más cuando empresas x conceptos x períodos es demasiado grande para devolver en una respuesta; la serie alineada completa siempre se materializa como un dataframe de df_<id> para tasas de crecimiento y diferenciales vía secedgar_dataframe_query
  • Una empresa que no se resuelve se reporta en failed_companies con una razón legible por máquina y la comparación continúa con el resto
  • Una empresa que no reporta un concepto se reporta en gaps con las etiquetas que se intentaron — nunca interpoladas
  • caveats saca a la superficie un filador que falta uno o dos trimestres de calendario, un concepto que se resolvió a una etiqueta XBRL retirada para una empresa, fines de período que difieren dentro de un período alineado, y conceptos cuya unidad difiere entre empresas

secedgar_search_concepts

Descubra nombres de conceptos XBRL admitidos antes de consultar datos financieros o comparaciones entre empresas.

  • Busque por nombre amigable, etiqueta o etiqueta XBRL sin procesar
  • Filtre por grupo de estados (income_statement, balance_sheet, cash_flow, per_share, entity_info) o taxonomía
  • Búsqueda inversa de etiquetas sin procesar como NetIncomeLoss a los nombres amigables admitidos
  • Superficies related_tags para conceptos con una etiqueta de definición alternativa de alta cobertura (p. ej. efectivo inclusivo de restricciones) para que los llamadores puedan descubrirlos antes de cribar
  • Filtrar por taxonomy: "ifrs-full" reduce el catálogo a conceptos con una etiqueta IFRS confirmada contra presentaciones 20-F en vivo; un concepto sin equivalente IFRS se deja fuera en lugar de mapearse a una suposición
  • Devuelve el mismo catálogo usado por secedgar_get_financials, secedgar_fetch_frames y secedgar://concepts

secedgar_dataframe_describe / secedgar_dataframe_query / secedgar_dataframe_drop

Análisis SQL en conversación sobre los dataframes que las herramientas que devuelven datos de secedgar_* materializan en un lienzo compartido respaldado por DuckDB. Cualquier llamada cuya respuesta lleve un campo dataset tiene un identificador de df_XXXXX_XXXXX: lea sus columnas con secedgar_dataframe_describe, luego analícelo con secedgar_dataframe_query — uniones, agregaciones, funciones de ventana, percentiles, SQL estándar de DuckDB.

  • Solo lectura por defecto. Las escrituras, DDL, DROP, COPY, PRAGMA, ATTACH y las funciones de tabla de archivos externos son rechazadas por la puerta SQL del framework. Los catálogos del sistema (information_schema, pg_catalog, sqlite_master, duckdb_*) están denegados en la capa puente para que los llamadores no puedan enumerar dataframes que aún no tienen un identificador. secedgar_dataframe_drop es la única herramienta destructiva y es opcional (EDGAR_DATAFRAME_DROP_ENABLED=true); el TTL gestiona la limpieza en caso contrario.
  • TTL por tabla. Cada dataframe envejece con su propio reloj (24 h por defecto, se puede anular con EDGAR_DATASET_TTL_SECONDS). El lienzo en sí utiliza el TTL deslizante del framework.
  • Encadenamiento de register_as. secedgar_dataframe_query puede persistir su resultado como un nuevo dataframe (df_XXXXX_XXXXX) con un TTL nuevo: encadena análisis sin volver a ejecutar la consulta fuente.
  • Los resultados limitados lo indican. Cuando row_limit acota la consulta, row_count_capped regresa true y row_count es ese límite en lugar de un total: aumenta row_limit (máx. 10000) o usa register_as para materializar el resultado completo, cuyo recuento es entonces exacto.

Recursos

URIDescripción
secedgar://conceptsConceptos financieros XBRL comunes agrupados por estado financiero, que asignan nombres amigables a etiquetas XBRL
secedgar://filing-typesTipos de presentaciones SEC comunes con descripciones, cadencia y casos de uso, además de las tablas completas de decodificación de códigos de 8-K para ambos regímenes de numeración

Prompts

PromptDescripción
secedgar_company_analysisGuía un análisis estructurado de las presentaciones SEC de una empresa pública: identifica presentaciones recientes, extrae tendencias financieras, destaca factores de riesgo y señala eventos materiales

Características

Construido sobre @cyanheads/mcp-ts-core:

  • Definiciones declarativas de herramientas: un archivo por herramienta, el framework gestiona el registro y la validación
  • Esquemas de salida estructurados con formato automático para visualización legible por humanos
  • Manejo unificado de errores en todas las herramientas
  • Autenticación conectable (none, jwt, oauth)
  • Registro estructurado con contexto por solicitud
  • Se ejecuta localmente (stdio/HTTP) desde el mismo código base

Específico de SEC EDGAR:

  • Cliente HTTP con límite de velocidad que respeta el límite de 10 req/s de la SEC con retraso automático entre solicitudes
  • Resolución de CIK a partir de tickers (incluidos ETFs y fondos mutuos mediante company_tickers_mf.json), nombres de empresas (actuales y anteriores) o números CIK sin procesar con caché local; normalización de sufijos corporativos en los pases de nombres y tickers de clases de acciones con puntos (BRK.B) resueltos a la forma con guiones de la SEC; sugerencias de trigramas de coincidencia cercana en consultas de nombres y tickers con cero resultados; activo former-names.json comprometido para la resolución de nombres anteriores (Facebook → Meta, Square → Block)
  • Mapeo de nombres de conceptos XBRL amigables con manejo de cambios históricos de etiquetas
  • Catálogo de conceptos buscable con metadatos de grupo de estados financieros y búsqueda inversa de etiquetas XBRL
  • Conversión de HTML a texto para documentos de presentaciones mediante html-to-text
  • Análisis SQL en conversación: las herramientas secedgar_* que devuelven datos materializan su resultado completo como un dataframe de lienzo respaldado por DuckDB: inspecciona sus columnas con secedgar_dataframe_describe y luego consúltalo con secedgar_dataframe_query
  • No se requieren claves API: SEC EDGAR es una API pública y gratuita

Primeros pasos

Instancia pública alojada

Hay una instancia pública disponible en https://secedgar.caseyjhand.com/mcp: no requiere instalación. Apunta cualquier cliente MCP a ella mediante Streamable HTTP:

{
  "mcpServers": {
    "secedgar-mcp-server": {
      "type": "streamable-http",
      "url": "https://secedgar.caseyjhand.com/mcp"
    }
  }
}

Autoalojado / Local

Añade lo siguiente a tu archivo de configuración del cliente MCP.

{
  "mcpServers": {
    "secedgar-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/secedgar-mcp-server@latest"],
      "env": {
        "EDGAR_USER_AGENT": "YourAppName your-email@example.com",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

O con npx (no se requiere Bun):

{
  "mcpServers": {
    "secedgar-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/secedgar-mcp-server@latest"],
      "env": {
        "EDGAR_USER_AGENT": "YourAppName your-email@example.com",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

Para Streamable HTTP, configura el transporte e inicia el servidor:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Requisitos previos

Instalación

  1. Clona el repositorio:
git clone https://github.com/cyanheads/secedgar-mcp-server.git
  1. Navega al directorio:
cd secedgar-mcp-server
  1. Instala las dependencias:
bun install
  1. Compila:
bun run build

Configuración

Toda la configuración se valida al inicio mediante esquemas Zod en src/config/server-config.ts. Variables de entorno clave:

VariableDescripciónPredeterminado
EDGAR_USER_AGENTObligatoria. Encabezado User-Agent para el cumplimiento de SEC. Formato: "AppName contact@email.com". SEC bloquea IPs sin un User-Agent válido.—
EDGAR_RATE_LIMIT_RPSMáximo de solicitudes/segundo a las APIs de SEC. No superar 10.10
EDGAR_TICKER_CACHE_TTLSegundos para almacenar en caché el archivo de búsqueda de tickers de empresas.3600
EDGAR_DATASET_TTL_SECONDSTTL por tabla para dataframes registrados en el lienzo. Ventana deslizante que se actualiza en cada operación de dataframe.86400
EDGAR_DATAFRAME_DROP_ENABLEDEstablecer en true para exponer secedgar_dataframe_drop: la única herramienta destructiva de este servidor. Desactivada por defecto; el TTL gestiona la limpieza, y la herramienta sigue apareciendo en la página de inicio HTTP como deshabilitada, con la bandera que la habilita.false
EDGAR_MIRROR_ENABLEDHabilita el espejo SQLite local de company_tickers + hechos de empresas XBRL para que la resolución de CIK y los datos financieros se lean desde disco en lugar de la API en vivo. Solo Node/Bun (se omite en Workers). Inicializa una vez con bun run mirror:init.false
EDGAR_MIRROR_PATHDirectorio que contiene las bases de datos SQLite del espejo../data/edgar-mirror
EDGAR_MIRROR_REFRESH_CRONCron para la actualización nocturna en proceso (solo transporte HTTP). Recomendado 0 9 * * *. Omitir para actualizar fuera de banda mediante bun run mirror:refresh.—
EDGAR_MIRROR_FALLBACK_LIVECuando el espejo falla (aún no sincronizado, o una presentación más reciente que la última actualización), recurre a la API SEC en vivo. Establecer false para lecturas estrictas solo con espejo.true
CANVAS_PROVIDER_TYPEMotor del lienzo. Predeterminado a duckdb; establecer en none para deshabilitar el lienzo (p. ej., al ejecutar en Cloudflare Workers, donde DuckDB no tiene compilación para V8-isolate).duckdb
MCP_TRANSPORT_TYPETransporte: stdio o httpstdio
MCP_HTTP_PORTPuerto del servidor HTTP3010
MCP_AUTH_MODEAutenticación: none, jwt o oauthnone
MCP_LOG_LEVELNivel de registro (debug, info, warning, error, etc.)info
LOGS_DIRDirectorio para archivos de registro (solo Node.js).<project-root>/logs

Ejecutar el servidor

Desarrollo local

  • Compila y ejecuta la versión de producción:

    bun run rebuild
bun run start:http   # or start:stdio

  • Ejecuta comprobaciones y pruebas:

    bun run devcheck     # Lints, formats, type-checks
bun run test         # Runs test suite

Docker

docker build -t secedgar-mcp-server .
docker run -e EDGAR_USER_AGENT="MyApp my@email.com" -p 3010:3010 secedgar-mcp-server

La imagen incluye la CLI del espejo, por lo que el espejo local (EDGAR_MIRROR_ENABLED) se puede inicializar, inspeccionar y actualizar dentro de un contenedor en ejecución:

docker exec <container> bun run mirror:verify    # sync status + sample reads
docker exec <container> bun run mirror:init      # one-time bootstrap (downloads the SEC bulk archive)
docker exec <container> bun run mirror:refresh   # re-ingest when the archive has been rebuilt

Estructura del proyecto

DirectorioPropósito
src/mcp-server/tools/definitions/Definiciones de herramientas (*.tool.ts). Diez herramientas de SEC EDGAR más tres herramientas de dataframe_* para análisis SQL.
src/mcp-server/resources/definitions/Definiciones de recursos. Conceptos XBRL y tipos de presentaciones.
src/mcp-server/prompts/definitions/Definiciones de prompts. Prompt de análisis de empresas.
src/services/edgar/Cliente API de SEC EDGAR, mapeo de conceptos XBRL, conversión de HTML a texto.
src/services/canvas-bridge/Adaptador sobre el DataCanvas del framework: acuñación de df_<id>, derivación de esquemas totalmente anulables, contabilidad TTL por tabla, denegación SQL de catálogos del sistema en la capa puente.
src/config/Análisis y validación de variables de entorno específicas del servidor con Zod.
tests/Pruebas unitarias y de integración, que reflejan la estructura de src/.

Guía de desarrollo

Consulta CLAUDE.md y AGENTS.md para las pautas de desarrollo y las reglas arquitectónicas. La versión breve:

  • Los manejadores lanzan excepciones, el framework las captura: sin try/catch en la lógica de herramientas
  • Usa ctx.log para el registro y ctx.state para el almacenamiento
  • Registra nuevas herramientas y recursos en los arreglos de createApp()

Contribuciones

Se aceptan problemas y solicitudes de extracción. Ejecuta comprobaciones y pruebas antes de enviar:

bun run devcheck
bun run test

Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0. Consulta el archivo LICENSE para más detalles.