secedgar-mcp-server

---

Ferramentas

Quatorze ferramentas para consultar dados SEC EDGAR, além de três para análises SQL sobre os dataframes de canvas com suporte a DuckDB que essas ferramentas materializam:

Ferramenta	Descrição
secedgar_company_search	Encontre empresas e recupere informações da entidade com arquivamentos recentes opcionais
secedgar_search_filings	Pesquise arquivamentos EDGAR desde 1993 — texto completo (2001+) além de navegação com suporte a arquivo para intervalos anteriores a 2001
secedgar_get_filing	Busque metadados e conteúdo de documentos de um arquivamento específico
secedgar_get_financials	Obtenha dados financeiros históricos XBRL de uma empresa
secedgar_get_snapshot	Perfil financeiro em uma única chamada — o valor mais recente de cada conceito suportado, agrupado por demonstrativo
secedgar_get_material_events	Arquivamentos 8-K com códigos de item decodificados e filtráveis — lucros, mudanças de diretores, não confiabilidade
secedgar_get_insider_transactions	Transações de insider Form 4 / 4-A (compras, vendas, doações, concessões, exercícios) analisadas a partir do XML de propriedade
secedgar_get_institutional_holdings	Participações institucionais trimestrais 13F-HR analisadas a partir da tabela de informações
secedgar_find_holders	Consulta reversa de 13F — quais gestores institucionais reportaram participação em um emissor
secedgar_get_beneficial_owners	Acionistas majoritários (5%+) de um emissor, analisados a partir de arquivamentos estruturados SCHEDULE 13D / 13G
secedgar_get_fund_holdings	Participações em carteiras de ETFs e fundos mútuos a partir do relatório trimestral NPORT-P
secedgar_fetch_frames	Busque frames XBRL da SEC para um conceito × um período em todas as empresas reportantes
secedgar_compare_companies	Compare empresas nomeadas em vários conceitos, alinhadas por períodos de calendário
secedgar_search_concepts	Descubra nomes de conceitos XBRL suportados ou faça consulta reversa de uma tag bruta
secedgar_dataframe_describe	Liste dataframes de canvas com procedência, TTL e esquema
secedgar_dataframe_query	Execute um SELECT de instrução única nos dataframes
secedgar_dataframe_drop	Descarte um dataframe de canvas pelo nome. Opcional via EDGAR_DATAFRAME_DROP_ENABLED=true — desativado por padrão, pois o TTL já cuida da limpeza, e não pode ser chamado até que a flag seja definida

secedgar_company_search

Ponto de entrada para a maioria dos fluxos de trabalho EDGAR — resolva tickers, nomes ou CIKs para detalhes da entidade.

• Suporta símbolos de ticker (AAPL, VOO), nomes de empresas (Apple) ou números de CIK (320193); um ticker de ação com múltiplas classes resolve em qualquer forma (BRK-B ou BRK.B)
• ETFs e fundos mútuos resolvem por ticker via company_tickers_mf.json; resultados de fundos incluem series_id e class_id para escopo em etapas posteriores
• Nomes atuais e anteriores de empresas são resolvidos (Facebook → Meta Platforms, Square → Block)
• A forma do sufixo corporativo não precisa corresponder ao registro (Beacon Financial Corporation → Beacon Financial Corp); Corp, Inc, Co e Ltd permanecem distintos entre si, pois registrantes separados diferem apenas por qual deles usam (TORO CO vs TORO CORP.)
• Sugestões de correspondência aproximada em busca de nome ou ticker sem resultados (ex.: Microsfot → MICROSOFT CORP / MSFT, CSWI → CSW INDUSTRIALS, INC. / CSW)
• Opcionalmente inclui arquivamentos recentes com filtragem por tipo de formulário
• Filtragem por data (filed_after / filed_before) e filtros de formulário subpreenchidos paginam para o arquivo de submissões mais antigas, alcançando arquivamentos anteriores à janela recente de ~1000 entradas (ex.: um 10-K de 2005); history_scanned_through divulga a profundidade da varredura, e o histórico filtrado completo é materializado como um dataframe df_<id> quando excede o limite inline filing_limit
• Retorna metadados da entidade: código SIC, bolsas, fim do ano fiscal, estado de incorporação

---

secedgar_search_filings

Pesquise arquivamentos EDGAR desde 1993. A busca em texto completo cobre 2001-presente (o piso do índice EFTS); intervalos de data anteriores a 2001 são servidos dos arquivos — correspondência de texto completo anterior a 2001 requer escopo de entidade.

• Frases exatas ("material weakness"), operadores booleanos (revenue OR income), curingas (account*)
• Segmentação de entidade dentro da string de consulta (cik:320193 ou ticker:AAPL) — com escopo no servidor por CIK, então arquivamentos feitos sob um nome anterior da empresa (mesmo CIK) são incluídos; um ticker de ação com múltiplas classes resolve em qualquer forma (ticker:BRK-B ou ticker:BRK.B)
• Modo de navegação: omita query para listar arquivamentos por tipo de formulário (forms=["S-1"]) e/ou entidade (ticker:/cik:), opcionalmente restringido por data — um intervalo de datas simples não é uma busca válida e deve ser combinado com formulários ou segmentação de entidade
• Intervalos de data anteriores a 2001 (até 1993) são roteados para os arquivos: um intervalo com escopo de entidade lê o histórico completo de submissões do arquivador; um intervalo de formulários/data sem escopo navega pelo índice completo trimestral. Cada linha carrega um campo source (efts / submissions / full-index), preservado no dataframe df_<id>
• Texto livre anterior a 2001 é correspondido pela leitura de documentos, então precisa de escopo ticker:/cik: para limitar o trabalho: o pré-filtro de formulário + data seleciona candidatos, até 50 são lidos, e scan relata candidatos / varridos / correspondidos em vez de apresentar uma leitura parcial como completa. A taxa de requisição da SEC é o custo — cerca de 5s para uma varredura completa de 50 documentos. Cada leitura cobre o accession completo .txt (arquivamentos anteriores a 1997 não expõem URL por documento), então uma correspondência pode estar em um anexo em vez do corpo do formulário solicitado
• Um intervalo que cruza 2001-01-01 é dividido no limite e mesclado: o índice de texto completo serve 2001 em diante, os arquivos servem o restante. period_ending, ticker, file_description, sic e location existem apenas em linhas source: efts, então um resultado mesclado os carrega em algumas linhas e não em outras
• Filtragem por intervalo de datas, filtragem por tipo de formulário, paginação até 10.000 resultados
• Retorna distribuição de formulários para buscas de acompanhamento mais restritas
• Quando a janela com escopo de entidade excede o limite inline, a janela EFTS já buscada é materializada como um dataframe df_<id> — consulte-o com secedgar_dataframe_query

---

secedgar_get_filing

Busque metadados e conteúdo de documentos de um arquivamento específico pelo número de accession.

• Aceita números de accession no formato com ou sem hífen
• Converte arquivamentos HTML em texto simples legível
• Limite de conteúdo configurável (1K–200K caracteres, padrão 50K)
• Pode buscar anexos específicos pelo nome do documento
• Entradas binárias — páginas escaneadas, anexos PDF, arquivos empacotados e planilhas — são marcadas como binary no catálogo de documentos e rejeitadas com um erro binary_document em vez de serem retornadas como bytes decodificados
• Paginação por deslocamento para documentos grandes (10-K, S-1/A podem exceder 1M caracteres): passe next_offset de uma resposta truncada como offset na próxima chamada para continuar a leitura; respostas truncadas na primeira página incluem um outline detectado (cabeçalhos com deslocamentos) para navegação direcionada
• Segmentação por seção via parâmetro section: salta diretamente para um cabeçalho nomeado por correspondência de substring que ignora maiúsculas/minúsculas, estilo de espaços em branco e estilo de aspas (ex.: "risk factors", "item 7", "certain relationships"), então um cabeçalho copiado do sumário resolve independentemente de carregar os espaços não separáveis e aspas curvas do arquivamento ou os simples; em caso de falha, o erro carrega o sumário detectado para que você possa escolher o cabeçalho correto
• O texto extraído é armazenado em cache por accession + document (LRU limitado, 8 entradas), tornando chamadas paginadas subsequentes baratas

---

secedgar_get_financials

Obtenha dados financeiros históricos XBRL de uma empresa com resolução amigável de nomes de conceitos.

• Nomes amigáveis como "revenue", "net_income", "eps_diluted" são resolvidos automaticamente para as tags XBRL corretas
• Lida com mudanças históricas de tags (ex.: reconhecimento de receita ASC 606)
• Deduplicação automática para um valor por período de calendário padrão
• Filtre por períodos anuais, trimestrais ou todos
• limit opcional limita a série inline aos N períodos mais recentes; a série completa permanece consultável via dataframe df_<id>
• Resultados trimestrais carregam uma entrada caveats nomeando cada trimestre de calendário ausente da série com tags de frame — a SEC reporta o 4º trimestre fiscal como o residual do 10-K, então o trimestre de calendário que o 4º trimestre fiscal abrange não tem valor trimestral discreto (incluindo arquivadores de ano fiscal de calendário), e um arquivador cujos outros trimestres fiscais abrangem durações não calendárias perde um segundo trimestre da mesma forma
• Uma entrada adicional caveats quando o conceito foi resolvido para uma tag XBRL que a SEC aposentou da taxonomia — isso só acontece quando nenhuma tag atual reporta para o arquivador, e a série pode parar anos antes
• Veja o recurso secedgar://concepts para o mapeamento completo

---

secedgar_get_snapshot

Construa um perfil financeiro de empresa em uma única chamada em vez de uma sequência de chamadas secedgar_get_financials.

• Lê o payload completo de companyfacts do arquivador uma vez, então resolve cada conceito suportado contra ele
• Mesma deduplicação de frames e prioridade de tags que secedgar_get_financials, então os dois concordam para qualquer conceito que ambos cobrem
• Conceitos de duração (demonstrativo de resultados, fluxo de caixa, por ação) reportam seu último ano completo e último trimestre único; conceitos de balanço patrimonial e informações da entidade reportam seu valor mais recente no tempo
• Conceitos que o arquivador não reporta são listados sob gaps com as tags XBRL que foram tentadas — nunca preenchidos com zero ou interpolados
• Arquivos IFRS resolvem através das variantes de tags IFRS mapeadas via taxonomy: "ifrs-full", que cobre demonstrativo de resultados, balanço patrimonial, fluxo de caixa e conceitos por ação; cada linha reporta a taxonomia da qual seu valor veio
• Perfil compacto de registro único — sem dataframe; use secedgar_get_financials quando precisar de uma série temporal

---

secedgar_get_insider_transactions

Superficie a atividade de insider Form 4 / 4-A para uma empresa analisando o XML de propriedade. Declarações iniciais Form 3 e declarações anuais Form 5 não são cobertas — alcance-as com secedgar_search_filings (forms: ["3", "5"]) além de secedgar_get_filing.

• Pessoa reportante, relação com o emissor (diretor, executivo + título, proprietário de 10%) e data da transação
• Código de transação mapeado para um tipo legível (compra, venda, doação, concessão, exercício, …); ações sinalizadas por adquiridas/alienadas
• Preço por ação e ações possuídas após cada transação; cobre linhas não derivativas (mercado aberto) e derivativas (opção/RSU)
• Filtre por transaction_type (purchase, sale, all); varre os arquivamentos mais recentes primeiro
• O conjunto completo de transações analisadas dos arquivamentos recentes varridos é materializado como um dataframe df_<id> (a lista inline é uma prévia limitada a limit) — consulte-o com secedgar_dataframe_query para agregar compra/venda líquida por insider

---

secedgar_get_institutional_holdings

Superficie participações institucionais trimestrais 13F-HR analisando a tabela de informações.

• Passe o arquivador institucional (CIK ou nome legal completo, ex.: 0000102909 para a Vanguard) para ver o que ele detém; para a direção inversa — quais gestores detêm uma determinada empresa — use secedgar_find_holders, cujos resultados de filer_cik alimentam diretamente esta ferramenta
• Cada posição: nome do emissor, CUSIP, valor de mercado (USD inteiro), ações/principal e put/call; linhas brutas também trazem a discricionariedade de investimento
• Sub-linhas para o mesmo título (uma por gestor/conta) são consolidadas em posições distintas ordenadas por valor por padrão — passe consolidate: false para linhas brutas do arquivamento
• Resolve o nome do gestor do arquivamento e o trimestre de referência a partir da página de capa; direcione um trimestre específico com quarter (ex.: "2025-Q4")
• total_holdings_in_filing conta linhas brutas da tabela de informações; total_positions conta posições distintas após consolidação (ambos antes de limit)
• Navegue por uma tabela de informações grande com offset — a resposta ecoa o offset efetivo e retorna next_offset enquanto houver linhas, para que cada posição permaneça acessível mesmo quando o canvas estiver desabilitado
• O conjunto completo de posições analisadas é materializado como um dataframe df_<id> (a lista inline é uma página de limit linhas) — consulte-o com secedgar_dataframe_query para agregação do arquivamento completo ou junções entre trimestres em cusip + reporting_period

---

secedgar_find_holders

Busca reversa de 13F: quais gestores institucionais reportaram uma posição em um emissor, para um trimestre de referência.

• Buscar por cusip corresponde ao identificador que a própria tabela de informações do 13F carrega — o caminho preciso. Louisiana-Pacific Q1 2026 retorna 451 arquivamentos por CUSIP 546347105 contra 43 pela frase "LOUISIANA-PACIFIC CORP"; o caminho por nome tanto subcorresponde (gestores escrevem o nome de formas diferentes) quanto sobrecorresponde (um emissor não relacionado compartilhando uma palavra)
• Um CUSIP não é derivável de um ticker em nenhum lugar do EDGAR — leia um de qualquer resultado de secedgar_get_institutional_holdings, ou recorra ao caminho por nome
• quarter direciona um período de referência ("2026-Q1"); omita-o para o trimestre mais recente cujo prazo de arquivamento de 45 dias já passou. O trimestre aplicado e sua janela de arquivamento são ecoados de volta
• Os arquivamentos são mantidos pelo período que reportam, não pela data em que foram arquivados, então emendas que reafirmam um trimestre mais antigo (cerca de 6% de qualquer janela) não caem na lista de detentores do trimestre errado
• Até 500 linhas de arquivadores são buscadas por chamada; total_filings reporta a contagem total e dataset.truncated sinaliza quando existem mais
• A lista não é classificada. A relevância da busca do EDGAR não carrega nenhum sinal sobre o tamanho da posição — leia a posição real de um gestor passando seu filer_cik para secedgar_get_institutional_holdings

---

secedgar_get_beneficial_owners

As participações de 5% ou mais em um emissor — a camada de acionistas relevantes entre os insiders do Formulário 4 e os portfólios 13F. A entrada é o emissor, a empresa que está sendo detida.

• 13D é o formulário ativista e carrega o propósito declarado da transação pelo arquivador; 13G é o formulário passivo e não tem item de propósito algum, que é a diferença substantiva entre uma participação que pretende influenciar o controle e uma que não pretende. Filtre com form_kind
• Cada pessoa que reporta é listada separadamente. Poder de voto, poder dispositivo e percentual da classe são reportados por pessoa mesmo em um arquivamento conjunto onde vários fundos e seu principal controlador reportam as mesmas ações subjacentes — somar esses percentuais conta a posição em dobro
• A cobertura começa em 2024-12-18, quando a SEC substituiu os arquivamentos de texto legados SC 13D / SC 13G por XML estruturado sob os nomes atuais SCHEDULE 13D / SCHEDULE 13G. Participações anteriores são legíveis mas não analisáveis, e legacy_filings_before_coverage reporta quantas o emissor tem — alcance-as com secedgar_search_filings e leia-as com secedgar_get_filing
• Emendas carregam a posição atual e são incluídas por padrão; include_amendments=false deixa apenas os arquivamentos que abriram uma posição
• O conjunto completo analisado registra-se como um dataframe df_<id> com uma linha por pessoa que reporta, então ele se junta aos dataframes de insiders e 13F pelo CIK do emissor

---

secedgar_get_fund_holdings

O que um ETF ou fundo mútuo possui, a partir do relatório de portfólio NPORT-P que arquiva trimestralmente — o inverso das ferramentas de propriedade, que respondem quem possui uma empresa.

• A entrada é o fundo: um ticker (VOO), um ID de série de fundo da SEC (S000002839) ou um CIK. Trusts de fundos são indexados por ticker e série em vez de por nome, então nomeie o registrante por CIK a menos que o próprio fundo negocie sob esse nome (SPDR S&P 500 ETF Trust)
• Um NPORT-P cobre exatamente uma série de fundo e um trust registrante arquiva um relatório por série por período, então um trust que opera vários fundos precisa que o fundo específico seja nomeado. Um registrante que resolve para mais de uma série retorna com as séries listadas, cada uma com seu ticker; um cujas séries não têm ticker é roteado lendo a série do seu relatório mais recente, porque o histórico de arquivamento de um trust intercala fundos cujos trimestres fiscais terminam em meses diferentes
• Cada resultado é datado de report_period_date. Os relatórios são publicados cerca de dois meses após o período que cobrem, então as participações são o portfólio naquela data, não hoje; publication_lag_days declara a lacuna. Direcione um período anterior com report_date, escolhido a partir do available_report_periods em qualquer resposta
• As posições carregam o nome do título, CUSIP/ISIN/LEI onde o arquivador os reporta, saldo de ações, valor em USD e percentual dos ativos líquidos, junto com ativos líquidos, ativos totais e passivos totais no nível do fundo
• As posições retornam primeiro as maiores por percentual dos ativos líquidos, uma página de limit linhas de offset. Um fundo de índice amplo reporta milhares — o relatório mais recente do Vanguard Total Stock Market carrega 3.524 — então o relatório completo registra-se como um dataframe df_<id> para agregação e para juntar os dataframes 13F e de insiders por CUSIP

---

secedgar_get_material_events

O histórico de 8-K de uma empresa com códigos de item decodificados e filtráveis — a única superfície que pode filtrar pelo que o evento realmente foi, em vez de pelo formulário.

• Filtre com items (ex.: ["2.02"] para resultados de operações, ["5.02"] para saídas de executivos, ["4.02"] para não confiabilidade); secedgar_search_filings e secedgar_company_search não conseguem ver itens de forma alguma
• Dois regimes de numeração são ambos aceitos e decodificados: o esquema pontilhado em vigor desde 2004-08-23, e os inteiros únicos anteriores (o legado 12 é o ancestral de 2.02, 9 de 7.01). A decodificação depende da forma do código, então um arquivamento que atravessa a mudança nunca é decodificado incorretamente, e uma janela que a atravessa precisa de ambos os códigos no filtro
• item_distribution conta cada código na janela escaneada antes do filtro, então um filtro com zero resultados retorna com os itens que estão presentes em vez de um beco sem saída
• Uma janela de datas pagina no arquivo de submissões mais antigas, alcançando arquivamentos 8-K que precedem a janela recente de ~1000 arquivamentos; history_scanned_through divulga a profundidade do escaneamento
• A tabela completa de decodificação está no recurso secedgar://filing-types
• O conjunto completo filtrado materializa-se como um dataframe df_<id> com códigos de item em cada linha — frequência de itens ao longo do tempo está a um secedgar_dataframe_query de distância

---

secedgar_fetch_frames

Busque frames XBRL da SEC para um conceito × um período em todas as empresas que reportam.

• Mesmos nomes de conceito amigáveis que secedgar_get_financials
• Suporta períodos anuais (CY2023), trimestrais (CY2024Q2) e instantâneos (CY2023Q4I)
• A resposta inline retorna uma página das empresas classificadas (ordenação + limite), com enriquecimento de ticker
• Caminhe mais abaixo na classificação com offset — a resposta ecoa o offset efetivo e retorna next_offset enquanto houver empresas, para que classificações além da primeira página permaneçam acessíveis mesmo quando o canvas estiver desabilitado
• A resposta completa de frames (todos os reportadores, tipicamente 2k–10k linhas) é materializada como um dataframe df_<id> — consulte-o com secedgar_dataframe_query
• related_tags sinaliza tags de definição alternativa que alguns arquivadores usam como linha primária (ex.: cash → total inclusivo de caixa restrita, equity → total inclusivo de NCI), para que uma triagem de universo inteiro na tag base não seja silenciosamente sub-inclusiva — consulte-as separadamente

---

secedgar_compare_companies

Compare 2-10 empresas nomeadas em 1-8 conceitos, alinhados em períodos de calendário — a forma intermediária entre secedgar_get_financials (uma empresa ao longo do tempo) e secedgar_fetch_frames (um período em todo o mercado).

• Uma leitura de companyfacts por empresa, resolvida através da mesma deduplicação de frames e prioridade de tags que secedgar_get_financials
• Conceitos de balanço patrimonial e informações de entidade alinham-se no ano ou trimestre de calendário em que seu instantâneo pontual cai, então ficam na mesma matriz que linhas de demonstração de resultados; cada célula mantém seu frame XBRL subjacente
• periods limita a matriz inline (1-12, padrão 4) e a janela encolhe ainda mais quando empresas x conceitos x períodos é grande demais para retornar em uma resposta; a série completa alinhada é sempre materializada como um dataframe df_<id> para taxas de crescimento e spreads via secedgar_dataframe_query
• Uma empresa que falha em resolver é reportada em failed_companies com um motivo legível por máquina e a comparação prossegue com o restante
• Uma empresa que não reporta um conceito é reportada em gaps com as tags que foram tentadas — nunca interpolada
• caveats revela um arquivador faltando um ou dois trimestres de calendário, um conceito que resolveu para uma tag XBRL aposentada para uma empresa, fins de período que diferem dentro de um período alinhado, e conceitos cuja unidade difere entre empresas

---

secedgar_search_concepts

Descubra nomes de conceitos XBRL suportados antes de consultar dados financeiros ou comparações entre empresas.

• Busque por nome amigável, rótulo ou tag XBRL bruta
• Filtre por grupo de demonstração (income_statement, balance_sheet, cash_flow, per_share, entity_info) ou taxonomia
• Busca reversa de tags brutas como NetIncomeLoss para os nomes amigáveis suportados
• Revela related_tags para conceitos com uma tag de definição alternativa de alta cobertura (ex.: caixa inclusivo de caixa restrita) para que chamadores possam descobri-los antes de triar
• Filtrar por taxonomy: "ifrs-full" restringe o catálogo a conceitos com uma tag IFRS confirmada contra arquivamentos 20-F ao vivo; um conceito sem equivalente IFRS é deixado de fora em vez de mapeado para um palpite
• Retorna o mesmo catálogo usado por secedgar_get_financials, secedgar_fetch_frames e secedgar://concepts

---

secedgar_dataframe_describe / secedgar_dataframe_query / secedgar_dataframe_drop

Análises SQL em conversa sobre os dataframes que as ferramentas que retornam dados secedgar_* materializam em um canvas compartilhado baseado em DuckDB. Qualquer chamada cuja resposta carregue um campo dataset detém um handle df_XXXXX_XXXXX: leia suas colunas com secedgar_dataframe_describe, depois analise-o com secedgar_dataframe_query — junções, agregações, funções de janela, percentis, SQL DuckDB padrão.

• Somente leitura por padrão. Gravações, DDL, DROP, COPY, PRAGMA, ATTACH e funções de tabela de arquivos externos são rejeitadas pelo gate SQL do framework. Catálogos do sistema (information_schema, pg_catalog, sqlite_master, duckdb_*) são negados na camada de ponte para que chamadores não possam enumerar dataframes para os quais não possuem um handle. secedgar_dataframe_drop é a única ferramenta destrutiva e é opt-in (EDGAR_DATAFRAME_DROP_ENABLED=true); TTL cuida da limpeza caso contrário.
• TTL por tabela. Cada dataframe envelhece em seu próprio relógio (padrão 24h, sobrescreva com EDGAR_DATASET_TTL_SECONDS). O canvas em si usa o TTL deslizante do framework.
• Encadeamento register_as. secedgar_dataframe_query pode persistir seu resultado como um novo dataframe (df_XXXXX_XXXXX) com um TTL novo — encadeie análises sem reexecutar a consulta de origem.
• Resultados limitados dizem isso. Quando row_limit limita a consulta, row_count_capped retorna true e row_count é esse limite em vez de um total — aumente row_limit (máx. 10000) ou use register_as para materializar o resultado completo, cuja contagem é então exata.

Recursos

URI	Descrição
secedgar://concepts	Conceitos financeiros XBRL comuns agrupados por demonstrativo, mapeando nomes amigáveis para tags XBRL
secedgar://filing-types	Tipos de arquivamento SEC comuns com descrições, cadência e casos de uso, além das tabelas completas de decodificação de códigos de item 8-K para ambos os regimes de numeração

Prompts

Prompt	Descrição
secedgar_company_analysis	Guia uma análise estruturada dos arquivamentos SEC de uma empresa pública: identifique arquivamentos recentes, extraia tendências financeiras, destaque fatores de risco e observe eventos materiais

Recursos

Construído sobre @cyanheads/mcp-ts-core:

• Definições declarativas de ferramentas — um arquivo por ferramenta, o framework cuida do registro e da validação
• Esquemas de saída estruturados com formatação automática para exibição legível por humanos
• Tratamento unificado de erros em todas as ferramentas
• Autenticação plugável (none, jwt, oauth)
• Logging estruturado com contexto por requisição
• Executa localmente (stdio/HTTP) a partir do mesmo código-fonte

Específico do SEC EDGAR:

• Cliente HTTP com limite de taxa respeitando o limite de 10 req/s da SEC com atraso automático entre requisições
• Resolução de CIK a partir de tickers (incluindo ETFs e fundos mútuos via company_tickers_mf.json), nomes de empresas (atuais e anteriores) ou números CIK brutos com cache local; normalização de sufixos corporativos nas buscas por nome e tickers com classes de ações pontilhadas (BRK.B) resolvidos para a forma hifenizada da SEC; sugestões de trigramas de correspondência aproximada em consultas de nome e ticker sem resultado; ativo former-names.json comprometido para resolução de nomes anteriores (Facebook → Meta, Square → Block)
• Mapeamento amigável de nomes de conceitos XBRL com tratamento de mudanças históricas de tags
• Catálogo de conceitos pesquisável com metadados de grupo de demonstrativo e busca reversa de tags XBRL
• Conversão de HTML para texto para documentos de arquivamento via html-to-text
• Análises SQL em conversa: as ferramentas secedgar_* que retornam dados materializam seu resultado completo como um dataframe de canvas com suporte a DuckDB — inspecione suas colunas com secedgar_dataframe_describe e depois consulte com secedgar_dataframe_query
• Nenhuma chave de API necessária — SEC EDGAR é uma API pública e gratuita

Primeiros passos

Instância pública hospedada

Uma instância pública está disponível em https://secedgar.caseyjhand.com/mcp — sem necessidade de instalação. Aponte qualquer cliente MCP para ela via Streamable HTTP:

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

Auto-hospedado / Local

Adicione o seguinte ao arquivo de configuração do seu 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"
      }
    }
  }
}

Ou com npx (sem necessidade de 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, defina o transporte e inicie o servidor:

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

Pré-requisitos

• Bun v1.3.0 ou superior.

Instalação

1. Clone o repositório:

git clone https://github.com/cyanheads/secedgar-mcp-server.git

2. Navegue até o diretório:

cd secedgar-mcp-server

3. Instale as dependências:

bun install

4. Compile:

bun run build

Configuração

Toda a configuração é validada na inicialização via esquemas Zod em src/config/server-config.ts. Principais variáveis de ambiente:

Variável	Descrição	Padrão
EDGAR_USER_AGENT	Obrigatório. Cabeçalho User-Agent para conformidade com a SEC. Formato: "AppName contact@email.com". A SEC bloqueia IPs sem um User-Agent válido.	—
EDGAR_RATE_LIMIT_RPS	Máximo de requisições/segundo para APIs da SEC. Não exceda 10.	10
EDGAR_TICKER_CACHE_TTL	Segundos para armazenar em cache o arquivo de consulta de tickers de empresas.	3600
EDGAR_DATASET_TTL_SECONDS	TTL por tabela para dataframes registrados no canvas. Janela deslizante tocada em toda operação de dataframe.	86400
EDGAR_DATAFRAME_DROP_ENABLED	Defina como true para expor secedgar_dataframe_drop — a única ferramenta destrutiva neste servidor. Desativada por padrão; TTL cuida da limpeza, e a ferramenta ainda é listada na página de aterrissagem HTTP como desativada, com o sinalizador que a ativa.	false
EDGAR_MIRROR_ENABLED	Ative o espelho SQLite local de company_tickers + fatos de empresas XBRL para que a resolução de CIK e os dados financeiros sejam lidos do disco em vez da API ao vivo. Apenas Node/Bun (ignorado em Workers). Inicialize uma vez com bun run mirror:init.	false
EDGAR_MIRROR_PATH	Diretório que contém os bancos de dados SQLite do espelho.	./data/edgar-mirror
EDGAR_MIRROR_REFRESH_CRON	Cron para a atualização noturna em processo (somente transporte HTTP). Recomendado 0 9 * * *. Omita para atualizar fora de banda via bun run mirror:refresh.	—
EDGAR_MIRROR_FALLBACK_LIVE	Quando o espelho falha (ainda não sincronizado, ou um arquivamento mais recente que a última atualização), recorra à API SEC ao vivo. Defina false para leituras estritas somente do espelho.	true
CANVAS_PROVIDER_TYPE	Motor do canvas. Padrão duckdb; defina como none para desativar o canvas (por exemplo, ao executar em Cloudflare Workers, onde DuckDB não tem build para isolado V8).	duckdb
MCP_TRANSPORT_TYPE	Transporte: stdio ou http	stdio
MCP_HTTP_PORT	Porta do servidor HTTP	3010
MCP_AUTH_MODE	Autenticação: none, jwt ou oauth	none
MCP_LOG_LEVEL	Nível de log (debug, info, warning, error, etc.)	info
LOGS_DIR	Diretório para arquivos de log (somente Node.js).	<project-root>/logs

Executando o servidor

Desenvolvimento local

• Compile e execute a versão de produção:

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

• Execute verificações e testes:

  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

A imagem inclui a CLI do espelho, então o espelho local (EDGAR_MIRROR_ENABLED) pode ser inicializado, inspecionado e atualizado dentro de um contêiner em execução:

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

Estrutura do projeto

Diretório	Finalidade
src/mcp-server/tools/definitions/	Definições de ferramentas (*.tool.ts). Dez ferramentas SEC EDGAR mais três ferramentas dataframe_* para análises SQL.
src/mcp-server/resources/definitions/	Definições de recursos. Conceitos XBRL e tipos de arquivamento.
src/mcp-server/prompts/definitions/	Definições de prompts. Prompt de análise de empresas.
src/services/edgar/	Cliente da API SEC EDGAR, mapeamento de conceitos XBRL, conversão de HTML para texto.
src/services/canvas-bridge/	Adaptador sobre o framework DataCanvas: cunhagem de df_<id>, derivação de esquema totalmente anulável, contabilidade de TTL por tabela, negação SQL de catálogos do sistema na camada de ponte.
src/config/	Análise e validação de variáveis de ambiente específicas do servidor com Zod.
tests/	Testes unitários e de integração, espelhando a estrutura src/.

Guia de desenvolvimento

Consulte CLAUDE.md e AGENTS.md para diretrizes de desenvolvimento e regras arquiteturais. A versão resumida:

• Handlers lançam, o framework captura — sem try/catch na lógica de ferramentas
• Use ctx.log para logging, ctx.state para armazenamento
• Registre novas ferramentas e recursos nos arrays createApp()

Contribuindo

Issues e pull requests são bem-vindos. Execute verificações e testes antes de enviar:

bun run devcheck
bun run test

Licença

Este projeto é licenciado sob a Licença Apache 2.0. Consulte o arquivo LICENSE para detalhes.