Sec Edgar Filings MCP

SEC EDGAR文件MCP服务器

一个模型上下文协议（MCP）服务器，使克劳德等人工智能助手能够与SEC EDGAR文件进行交互。无缝下载、转换和解析SEC财务文件。

🎯 特性

• 📄 PDF转Markdown：使用LlamaCloud或Docling将PDF文件解析为Markdown
• 🔄 HTML转PDF：将SEC EDGAR HTML/iXBRL文件转换为PDF
• 📥 下载SEC文件：自动从SEC EDGAR下载文件
• ⚡ 速率限制：遵守SEC的10次请求/秒限制
• 🐳 Docker支持：使用Docker轻松部署

📋 支持的归档类型

• 8-K：当前报告
• 10-Q：季度报告
• 10千：年度报告
• 定义14A：委托书（奖金）

🔧 先决条件

• Python 3.8+
• LlamaCloud API密钥（用于PDF解析）-从https://cloud.llamaindex.ai/
• 克劳德桌面（用于测试）

🚀 快速入门（Docker-推荐）

**⚡ 最快开始方式（\ cd "SEC EDGAR filings MCP"

### 2.创建虚拟环境

Windows

python -m venv venv venv\Scripts\activate

macOS/Linux

python3 -m venv venv source venv/bin/activate

### 3.安装依赖项

pip install -r requirements.txt

### 4.安装Playwright浏览器

playwright install chromium

### 5.配置环境

**创建 `.env` 模板中的文件：**

Copy example file

cp .env.example .env

Edit with your credentials

## 📖 用法

### Claude桌面配置

**配置文件位置：**

- **视窗**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

#### **选项1：使用Docker（推荐）**

首先启动Docker容器：

docker-compose up -d

然后添加此配置：

{ "mcpServers": { "sec-edgar": { "command": "docker", "args": [ "exec", "-i", "sec-edgar-mcp-server", "python", "/app/server.py" ], "toolTimeout": 500000 } } }

**✅ 优点：**

- 无需安装Python
- 包括所有依赖项
- 可复制环境

**⚠️ 重要提示：**

- 启动Claude Desktop之前，容器必须正在运行
- 跑 `docker-compose up -d` 第一
- 使用 `docker ps` 验证容器是否正在运行

______________________________________________________________________

#### **选项2：本地Python安装**

{ "mcpServers": { "sec-edgar": { "command": "C:\\Users\\YourName\\path\\to\\venv\\Scripts\\python.exe", "args": [ "C:\\Users\\YourName\\path\\to\\server.py" ], "env": { "LLAMA_CLOUD_API_KEY": "your_actual_api_key", "SEC_USER_AGENT": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" }, "toolTimeout": 500000 } } }

**Windows路径示例：**

- 使用venv： `C:\\Users\\YourName\\projects\\sec-edgar\\venv\\Scripts\\python.exe`
- 系统Python： `C:\\Python311\\python.exe`
- ✅ 使用双反睫毛(`\\`)或正斜杠(`/`)

**macOS/Linux：**

{ "mcpServers": { "sec-edgar": { "command": "/Users/yourname/projects/sec-edgar/venv/bin/python", "args": ["/Users/yourname/projects/sec-edgar/server.py"], "env": { "LLAMA_CLOUD_API_KEY": "your_actual_api_key", "SEC_USER_AGENT": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" }, "toolTimeout": 500000 } } }

______________________________________________________________________

## 💬 克劳德桌面提示示例

### 多种工具

**单提示挑战#1：苹果2021 8-K分析**

2021 애플 8-k 공시 다 숙지해줘

**预期工作流程：**

1. 下载苹果2021年8-K文件（CIK:0000320193）
1. 将HTML转换为PDF
1. 将PDF解析为markdown
1. 阅读并总结整个文件

**结果：**

✅ Successfully completed all steps automatically

Downloaded: html/apple_2021_8k/apple_20211109.htm Converted: pdf/apple_2021_8k.pdf Parsed: markdown/apple_2021_8k.md

Summary: 2021년 11월 9일자 애플 8-K 공시 - 주요 기업 변동사항 보고

주요 내용:

1. 새 이사 임명 (Item 5.02)

- Alex Gorsky (Johnson & Johnson 전 CEO) 임명 - 지명 및 기업지배구조 위원회 소속 - 연간 현금 보수: $100,000 (분기별 지급) - 초기 주식 부여: 486 RSU

1. 정관 개정 (Item 5.03)

- 이사회 정원 8명 → 9명 확대

1. 헬스케어 전문성 강화

- Gorsky의 J&J CEO 경험을 통한 헬스케어 분야 전문성 확보

______________________________________________________________________

**单一提示挑战#2：苹果2021 DEF 14A分析**

2021 애플 14def 다 숙지해줘

**预期工作流程：**

1. 下载苹果公司（CIK:0000320193）2021年DEF 14A文件
1. 将HTML转换为PDF
1. 将PDF解析为markdown（由于大小较大而创建多个块）
1. 自动恢复：用途 `list_markdown_files` 定位块
1. 按顺序读取所有块 `read_markdown_chunk`
1. 理解整个委托书

**结果：**

✅ Successfully completed with automatic recovery workflow

Downloaded: html/apple_2021_def14a/apple_20210223.htm Converted: pdf/apple_2021_def14a.pdf Parsed: 5 markdown chunks (total ~213KB) - apple_2021_def14a_chunk_1_of_5.md (50KB) - apple_2021_def14a_chunk_2_of_5.md (50KB) - apple_2021_def14a_chunk_3_of_5.md (50KB) - apple_2021_def14a_chunk_4_of_5.md (50KB) - apple_2021_def14a_chunk_5_of_5.md (12KB)

⚠️ Known Issue (UNFIXED): Problem: read_as_markdown returned "No result received from client-side tool execution"

Server Status: ✅ NORMAL - Server successfully creates chunk files - Server logs confirm normal operation - Server returns chunk file list

Claude Status: ❌ ERROR - Tool execution appears successful in Claude UI - But no response content received - Error: "No result received from client-side tool execution"

Root Cause: MCP protocol communication issue - Server → Claude transmission fails - NOT a server logic problem - Possibly related to response format or MCP protocol limitation

Status: UNFIXED (architectural/protocol-level issue)

✅ Workaround Applied: Used alternative tool chain to bypass the issue:

Step 1: read_as_markdown (Expected to fail, but creates chunk files) └─ Server creates 5 chunk files └─ Claude shows "No result" error

Step 2: list_markdown_files (Discovery) └─ Lists all markdown files in markdown/ directory └─ Confirms 5 chunk files were created

Step 3: read_markdown_chunk × 5 (Individual retrieval) └─ Reads apple_2021_def14a_chunk_1_of_5.md └─ Reads apple_2021_def14a_chunk_2_of_5.md └─ Reads apple_2021_def14a_chunk_3_of_5.md └─ Reads apple_2021_def14a_chunk_4_of_5.md └─ Reads apple_2021_def14a_chunk_5_of_5.md

Result: ✅ All content successfully retrieved

Summary: 2021년 2월 23일 애플 연례 주주총회 공시 (81페이지)

주요 내용:

1. 연례 주주총회

- 일시: 2021년 2월 23일 오전 9시 (PST) - 가상 회의 (COVID-19 대응) - 8명 이사 선출 안건

1. 이사회 구성 (다양성 강화)

- 이사 8명 후보: Bell, Cook, Gore, Jung, Levinson, Lozano, Sugar, Wagner - 50% 여성 리더십, 50% 소수집단 출신 - Monica Lozano 신규 이사 (2021.1월 임명)

1. 임원 보상 프로그램

- CEO Tim Cook: 2020년 총 보상 $14.8M * 기본급: $3M * 현금 인센티브: $10.7M (목표 대비 179% 달성) * 기타: $1M (보안, 항공기 사용) - NEO 평균 보상: ~$26M * 기본급: $1M * 현금 인센티브: $3.6M * 주식 보상: $21.7M (시간/성과 기반 RSU)

1. 2020년 재무 성과

- 매출: $274.5B (전년 대비 +6%) - 주당순이익: $3.28 (+10%) - 영업이익: $66.3B (+4%) - 주주환원: $90B (배당+자사주) - 총주주수익률(TSR): 1년 107%, 3년 203%, 5년 324%

1. 2021년 변경사항

- ESG 수정 요소 추가: Apple Values 기반 평가를 연간 인센티브에 반영 - CEO 장기 주식 보상: Tim Cook에게 2011년 이후 첫 신규 RSU 부여 (10년간 시총 $1.5T 증가, TSR 867% 성과 인정)

1. 기업 가치 실천 (2020년)

- COVID-19 대응: 마스크 3천만개, 안면보호구 1천만개 기부 - 탄소중립 목표: 2030년까지 공급망 포함 100% 달성 - 인종평등: $100M 투자 (교육, 경제평등, 형사사법 개혁) - 주택위기 해결: 캘리포니아 주택 프로젝트 $400M 투자

1. 주주 제안 (안건 4, 5)

- 안건 4: 대리접근권 개정 (이사 최소 2명 또는 20%) - 이사회 반대 - 안건 5: 임원 보상에 급여 비율 고려 - 이사회 반대 - 이사회 권고: 안건 1,2,3 찬성 / 안건 4,5 반대

1. 감사 정보

- 독립 감사인: Ernst & Young LLP (2009년부터) - 2020년 감사 비용: $22.2M * 감사: $17.6M, 세무: $3.4M, 기타: $1.2M

Key Insights:

• 81페이지 분량의 상세한 기업지배구조 및 보상 정책 공시
• 강력한 재무 성과와 주주가치 창출 (매출/이익 성장, 높은 TSR)
• 다양성과 ESG를 강화하는 이사회 및 경영진 구성
• 투명한 임원 보상 체계 (성과연동, 장기 인센티브 중심)
• 2021년부터 ESG 요소를 보상에 직접 반영하는 선진적 접근

______________________________________________________________________

## 🔀 Markdown分块系统

**为什么是Chunking？**

MCP客户端（Claude）有响应大小限制。大型SEC文件（10-K报告通常超过200000个字符）无法在单个工具响应中从服务器传输到Claude，即使服务器成功处理并返回了它们。

**它是如何工作的：**

1. 当 `read_as_markdown` 解析大型PDF（>50000个字符）
1. 内容会自动拆分为50000个字符块
1. 每个块另存为： `{filename}_chunk_{N}_of_{total}.md`
1. 工具返回块文件列表而不是全文
1. 然后克劳德可以打电话 `read_markdown_chunk` 读取特定块
1. 使用 `list_markdown_files` 查看所有可用块

**优点：**

- 处理任何大小的文件
- 符合MCP响应限制
- 允许选择性阅读文档部分
- 保留完整内容而不截断

______________________________________________________________________

## 🛠️ MCP工具

### 1. `read_as_markdown`

将PDF文件解析为Markdown格式。

**参数：**

- `input_file_path` （string）：相对于的PDF文件路径 `pdf/` 目录

**例子：**

Input: "Amazon.com Inc. - Form 10-K. For the Fiscal Year Ended 2024-12-31.pdf" Output: Markdown text content (or chunk file list for large documents)

**支持的解析器：**

- **LlamaCloud Llama提取物** （主要）：使用API进行高质量解析

**📦 自动分块：**

- 大于50000个字符的文档会自动拆分为块
- 每个块都另存为单独的块 `.md` 归档 `markdown/` 目录
- 返回块文件列表，而不是全文
- 使用 `read_markdown_chunk` 读取单个块的工具

**🔧 它是如何工作的（代码逻辑）：**

1. **路径解析**：将相对路径转换为绝对路径 `pdf/` 目录
1. **文件验证**：检查PDF文件是否存在
1. **API密钥验证**：验证是否已配置LLAMA_CLOUD_API_KEY
1. **LlamaCloud解析**:
   - 初始化 `LlamaParse` 具有API密钥的客户端
   - 呼叫 `load_data()` 将PDF解析为markdown
   - 在线程池中同步运行以避免阻塞
1. **分块逻辑**:
   - 检查标记长度是否大于50000个字符
   - 拆分为50KB的块： `chunks = [text[i:i+50000] for i in range(0, len(text), 50000)]`
   - 保存每个块： `{filename}_chunk_{N}_of_{total}.md`
1. **回报策略**:
   - 小文件（≤50K）：直接返回markdown文本
   - 大文件（>50K）：返回带块文件列表的格式化消息
   - ⚠️ Claude可能会对大文件显示“无结果”（MCP客户端限制）

**代码参考：**

Main workflow

markdown_text = await _parse_pdf_with_llamacloud(file_path) chunk_files = await _save_markdown_chunks(markdown_text, base_filename)

Chunking implementation

chunk_size = 50000 total_chunks = (total_length + chunk_size - 1) // chunk_size

for i in range(total_chunks): start_idx = i * chunk_size end_idx = min(start_idx + chunk_size, total_length) chunk_text = markdown_text[start_idx:end_idx]

______________________________________________________________________

### 2. `html_to_pdf`

将HTML/iXBRL文件转换为PDF格式。

**参数：**

- `input_file_path` （string）：相对于的HTML文件路径 `html/` 目录
- `output_file_path` （string）：相对于的PDF输出路径 `pdf/` 目录

**例子：**

Input: "html/Form 10-K/amzn-20241231.htm" Output: "pdf/amazon_10k_2024.pdf"

**🔧 它是如何工作的（代码逻辑）：**

1. **路径解析**：将HTML输入路径和PDF输出路径转换为绝对路径
1. **文件验证**：检查HTML文件是否存在，必要时创建输出目录
1. **Playwright浏览器启动**：以无头模式启动Chromium浏览器
1. **HTML加载**：使用加载本地HTML文件 `file://` 协议
   - `wait_until="networkidle"`：等待所有网络请求完成（CSS/images）
   - 大型SEC文件超时60秒
1. **PDF生成**：通话 `page.pdf()` 具有优化的设置
   - 格式：信纸（美国标准纸张尺寸）
   - 背景：已启用（保留SEC文档样式）
   - 边距：四周0.5英寸（提高可读性）
1. **文件稳定**：等待文件写入完成
   - 检查文件大小稳定性（2秒内进行10次检查）
   - 防止空文件错误

**代码参考：**

await page.goto(file_url, wait_until="networkidle", timeout=60000) await page.pdf( path=str(output_path), format="Letter", print_background=True, margin={"top": "0.5in", "right": "0.5in", "bottom": "0.5in", "left": "0.5in"} )

______________________________________________________________________

### 3. `download_sec_filing`

从EDGAR下载SEC文件。

**参数：**

- `cik` （string）：公司CIK编号（例如“0001018724”）
- `year` （整数）：申请年份（2021-2025）
- `filing_type` （字符串）：“8-K”|“10-Q”|“10-K”|“DEF 14A”
- `output_dir_path` （string）：相对于的输出目录 `html/`

**例子：**

CIK: "0001018724" Year: 2024 Filing Type: "10-K" Output: "amzn_2024_10k" Result: "html/amzn_2024_10k/amzn-20241231.htm"

**🔧 它是如何工作的（代码逻辑）：**

1. **输入验证**:
   - 验证年份范围（2021-2025）
   - 规范化CIK：删除前导零，填充到10位数字
1. **SEC API请求**:
   - 网址： `https://data.sec.gov/submissions/CIK{cik_padded}.json`
   - 在Chrome模拟中使用curl_cffi（防止403个错误）
   - 应用速率限制：请求之间延迟100ms（SEC 10req/s限制）
1. **归档搜索**:
   - 匹配文件 `reportDate` （回到 `filingDate` 如果不可用）
   - 筛选条件 `form_types` 对于指定的filing_type
   - 选择最近提交的文件（按报告日期降序排列）
1. **主文档命名**:
   - 从中提取股票代码 `output_dir_path` （例如。， `amzn_2024_8k` → `amzn`)
   - 格式化日期： `YYYY-MM-DD` → `YYYYMMDD`
   - 最终文件名： `{ticker}_{date}.{ext}` （例如。， `amzn_20241231.htm`)
1. **完整存档下载**:
   - 获取 `index.json` 获取完整的文件列表
   - 下载所有有速率限制的文件
   - 自动重命名主文档
1. **返回**：返回下载的主文档的相对路径

**代码参考：**

Rate limiting

await sec_rate_limiter.wait()

CIK normalization

cik_normalized = str(cik).lstrip("0") cik_padded = cik_normalized.zfill(10)

Filing search

matching_filings.sort(key=lambda x: x["reportDate"] or x["filingDate"], reverse=True) target_filing = matching_filings[0]

______________________________________________________________________

### 4. `list_markdown_files`

列出所有可用的markdown文件 `markdown/` 目录。

**参数：**

- 无

**例子：**

Output: List of markdown files with size and modification date

**🔧 它是如何工作的（代码逻辑）：**

1. **目录扫描**：扫描全部 `.md` 文件在 `markdown/` 目录
1. **文件元数据集合**:
   - 收集文件名、文件大小（字节）、修改时间
   - 用途 `Path.glob("*.md")` 用于模式匹配
1. **排序**：按修改时间降序排序（最新者优先）
1. **格式化输出**:
   - 粗体文件名
   - 大小：KB+字节显示
   - 修改时间： `YYYY-MM-DD HH:MM:SS` 格式
1. **使用提示**：添加使用说明 `read_markdown_chunk` 工具

**代码参考：**

for file_path in MARKDOWN_DIR.glob("*.md"): stat = file_path.stat() files.append({ 'name': file_path.name, 'size': stat.st_size, 'modified': stat.st_mtime })

files.sort(key=lambda x: x['modified'], reverse=True)

______________________________________________________________________

### 5. `read_markdown_chunk`

读取特定的markdown块文件（适用于大型文档）。

**参数：**

- `file_path` （string）：相对于基本目录的Markdown文件路径（例如，“Markdown/amazon_10k_2024_chunk_1_of_5.md”）

**例子：**

Input: "markdown/amazon_10k_2024_chunk_1_of_5.md" Output: Markdown content of that specific chunk

**🔧 它是如何工作的（代码逻辑）：**

1. **路径解析**:
   - 手柄 `markdown/` 前缀
   - 转换为绝对路径
1. **文件验证**：检查markdown文件是否存在
1. **异步文件读取**：用途 `aiofiles` 用于非阻塞读取（UTF-8编码）
1. **响应格式**:
   - 添加文件路径和大小标题
   - 添加分隔线(`---`)
   - 添加降价内容
1. **返回**：返回带元数据的格式化markdown文本

**代码参考：**

async with aiofiles.open(full_path, "r", encoding="utf-8") as f: content = await f.read()

result = f"📄 File: {file_path}\n" result += f"📊 Size: {file_size:,} characters\n\n" result += "---\n\n" result += content

______________________________________________________________________

## 📁 项目结构

SEC EDGAR filings MCP/ ├── server.py # Main MCP server ├── requirements.txt # Python dependencies ├── .env.example # Environment template ├── .env # Your config (not in git) ├── .gitignore # Git ignore rules ├── README.md # This file ├── Dockerfile # Docker config ├── docker-compose.yml # Docker Compose config ├── pdf/ # PDF files directory │ └── (downloaded/test PDFs) └── html/ # HTML/iXBRL files └── (downloaded filings)

## 🏢 常见公司CIK

|公司|CIK|
|---------|-----|
|亚马逊| 0001018724|
|苹果| 0000320193|
|微软| 0000789019|
|字母表（谷歌）| 0001652044|
|Meta（脸书）| 0001326801|
|特斯拉|0001318605|
|英伟达| 0001045810|

查找更多：https://www.sec.gov/edgar/searchedgar/companysearch.html

## 🔍 测试

### 与MCP检查员一起

npm install -g @modelcontextprotocol/inspector npx @modelcontextprotocol/inspector python server.py

### 手动测试

Test imports

python -c "import fastmcp; print('FastMCP OK')" python -c "from playwright.async_api import async_playwright; print('Playwright OK')"

Test server startup

python server.py

## 🐳 Docker安装详细信息

### 快速入门（预构建图像-推荐）

**⚡ 最快部署（约2秒）：**

1. Pull pre-built image from Docker Hub

docker-compose pull

2. Start container

docker-compose up -d

3. Verify

docker ps

**图片：** `momotime7584/sec-edgar-mcp:latest`

- 大小：约856 MB
- 拉动时间：1-2秒
- 包括：Python 3.11、LlamaCloud、Playwright、所有依赖项

### 有用的命令

View logs (for debugging)

docker-compose logs -f

Stop container (after testing)

docker-compose down

Check environment variables

docker exec sec-edgar-mcp-server env | grep -E "(LLAMA|SEC)"

______________________________________________________________________

## ⚠️ 故障排除

### “找不到PDF文件”

- 验证文件是否在 `pdf/` 目录
- 检查文件名（在Linux/macOS上区分大小写）
- 使用分配中的确切文件名

### “找不到HTML文件”

- 将HTML文件提取到 `html/` 目录
- 如果需要，维护子目录结构
- 检查路径分隔符(`/` vs `\`)

### “LlamaCloud API错误”

- 在中验证API密钥 `.env`
- 检查API信用/配额
- 服务器自动回退到Docling

### “超出费率限制”

- 服务器自动处理SEC速率限制
- 如果错误仍然存在，请等待1-2秒
- 检查用户代理是否配置正确

### “未安装Playwright浏览器”

playwright install chromium

### Claude Desktop未显示工具

- 完全重新启动克劳德桌面
- 验证JSON配置语法
- 检查服务器路径是否正确
- 在Claude Desktop日志中查找错误

**重要**：这个项目是为了教育目的。访问EDGAR数据时，请遵守SEC的使用政策和速率限制。