Name: SEC EDGAR文件解析服务
Author: momotime7584

使用说明

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-推荐）

⚡ 最快开始方式（<2分钟）：

1.先决条件

Docker 桌面版 已安装并正在运行
- Windows/macOS: 下载Docker桌面
- Linux: 安装Docker引擎
LlamaCloud API密钥

⚠️ 重要提示：首先启动Docker桌面！

验证Docker是否正在运行：

docker --version
docker ps

如果你看到“无法连接到Docker守护进程”，请启动Docker Desktop并等待它完全运行。

2.克隆和配置

git clone https://github.com/momotime7584/sec-edgar-filings-mcp.git
cd sec-edgar-filings-mcp 

# Create .env file
cp .env.example .env
# Edit .env with your LLAMA_CLOUD_API_KEY

所需配置：

# LlamaCloud API Key (get from https://cloud.llamaindex.ai/)
LLAMA_CLOUD_API_KEY=your_actual_api_key_here

# SEC API User-Agent (CRITICAL - use browser format!)
# ⚠️ IMPORTANT: Must use browser User-Agent to avoid 403 Forbidden errors
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

# Your email (optional but recommended)
SEC_FROM_EMAIL=your.email@example.com

🚨 关键：SEC_USER_AGENT格式

美国证券交易委员会API 需要一个类似浏览器的用户代理字符串。使用一个简单的格式，如 "YourName your.email@example.com" 将导致 403禁止的错误.

为什么？ 虽然美国证券交易委员会的文件建议进行简单的识别，但他们的服务器实际上会过滤请求，并更喜欢浏览器用户代理来防止自动抓取滥用。

✅ 使用上面显示的浏览器用户代理 （已在 .env.example)

3.启动服务器

# Download pre-built image (~1-2 seconds) and start
docker-compose pull
docker-compose up -d

✅ 完成！ MCP服务器现在正在具有所有依赖项的容器中运行。

4.配置克劳德桌面

看 Claude桌面配置下面的部分（使用Docker选项）。

🔧 替代安装（Python）

如果你不想使用Docker，可以直接用Python安装：

1.克隆存储库

git clone <your-repository-url>
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 공시 다 숙지해줘

预期工作流程：

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

结果：

✅ 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

2. 정관 개정 (Item 5.03)
   - 이사회 정원 8명 → 9명 확대

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

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

2021 애플 14def 다 숙지해줘

预期工作流程：

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

结果：

✅ 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명 이사 선출 안건

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

3. 임원 보상 프로그램
   - CEO Tim Cook: 2020년 총 보상 $14.8M
     * 기본급: $3M
     * 현금 인센티브: $10.7M (목표 대비 179% 달성)
     * 기타: $1M (보안, 항공기 사용)
   - NEO 평균 보상: ~$26M
     * 기본급: $1M
     * 현금 인센티브: $3.6M
     * 주식 보상: $21.7M (시간/성과 기반 RSU)
   
4. 2020년 재무 성과
   - 매출: $274.5B (전년 대비 +6%)
   - 주당순이익: $3.28 (+10%)
   - 영업이익: $66.3B (+4%)
   - 주주환원: $90B (배당+자사주)
   - 총주주수익률(TSR): 1년 107%, 3년 203%, 5년 324%

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

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

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

8. 감사 정보
   - 독립 감사인: 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，即使服务器成功处理并返回了它们。

它是如何工作的：

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

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

路径解析：将相对路径转换为绝对路径 pdf/ 目录
文件验证：检查PDF文件是否存在
API密钥验证：验证是否已配置LLAMA_CLOUD_API_KEY
LlamaCloud解析:
- 初始化 LlamaParse 具有API密钥的客户端
- 呼叫 load_data() 将PDF解析为markdown
- 在线程池中同步运行以避免阻塞
分块逻辑:
- 检查标记长度是否大于50000个字符
- 拆分为50KB的块： chunks = [text[i:i+50000] for i in range(0, len(text), 50000)]
- 保存每个块： {filename}_chunk_{N}_of_{total}.md
回报策略:
- 小文件（≤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"

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

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

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

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

代码参考：

# 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

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

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

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

路径解析:
- 手柄 markdown/ 前缀
- 转换为绝对路径
文件验证：检查markdown文件是否存在
异步文件读取：用途 aiofiles 用于非阻塞读取（UTF-8编码）
响应格式:
- 添加文件路径和大小标题
- 添加分隔线(---)
- 添加降价内容
返回：返回带元数据的格式化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的使用政策和速率限制。

使用说明

SEC EDGAR文件MCP服务器

🎯 特性

📋 支持的归档类型

🔧 先决条件

🚀 快速入门（Docker-推荐）

1.先决条件

2.克隆和配置

3.启动服务器

4.配置克劳德桌面

🔧 替代安装（Python）

1.克隆存储库

2.创建虚拟环境

3.安装依赖项

4.安装Playwright浏览器

5.配置环境

📖 用法

Claude桌面配置

选项1：使用Docker（推荐）

选项2：本地Python安装

💬 克劳德桌面提示示例

多种工具

🔀 Markdown分块系统

🛠️ MCP工具

1. read_as_markdown

2. html_to_pdf

3. download_sec_filing

4. list_markdown_files

5. read_markdown_chunk

📁 项目结构

🏢 常见公司CIK

🔍 测试

与MCP检查员一起

手动测试

🐳 Docker安装详细信息

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

有用的命令

⚠️ 故障排除

“找不到PDF文件”

“找不到HTML文件”

“LlamaCloud API错误”

“超出费率限制”

“未安装Playwright浏览器”

Claude Desktop未显示工具

相关 MCP

SEC EDGAR金融数据MCP服务器

PDF转Markdown服务

HWP文档自动化工具

金融数据服务

图像转换服务器

SEC EDGAR文件访问工具

1. `read_as_markdown`

2. `html_to_pdf`

3. `download_sec_filing`

4. `list_markdown_files`

5. `read_markdown_chunk`