SEC Intelligence

🔎 SEC Intelligence MCP — 基于文档的金融 AI

向 Claude Desktop 提出有关 SEC 文件的真实问题——10-K、10-Q、8-K——即可获得直接引用自实际文件文本的答案，每项说法都附有精确到具体章节（如有页码，也会注明）的引文。不是来自训练数据的摘要，也不是猜测。

立即试用： uvx sec-intelligence-mcp — 参见下文的快速安装。

有何不同

大多数与金融相关的 MCP 服务都是数据 API 封装：它们从数据库中返回数字（营收、EPS、股价）。我们调查过的 MCP 服务都不会读取实际的文件文档，因此都无法回答需要理解公司管理层实际说过什么的问题——例如，“NVIDIA 管理层如何解释数据中心营收激增？”或“Amazon 的前瞻指引语气在不同季度之间是否发生了变化？”

此服务会检索并引用真实的文件文本，每项说法都附有引文；其答案生成提示词明确规定，如果检索到的段落中没有答案，就不得使用已有的通用知识——我们已通过实时测试验证：询问 NVIDIA 并不存在的“Mars operations”，会正确回答“文件中未提及”，而不是编造答案。它还提供自动化 RAGAS 评估工具（参见评估结果），用 50 个真实问题衡量这一点，而不只是声称如此。

---

🚀 快速安装

已发布到 PyPI：https://pypi.org/project/sec-intelligence-mcp/。无需克隆或构建—— uv 会按需获取并运行：

uvx sec-intelligence-mcp

安装就完成了。再做两件事，就可以在 Claude Desktop 中使用了：

1. 获取免费的 API 密钥

四项操作总共不到 5 分钟，完全不需要信用卡。

变量	获取方式	必需？
GEMINI_API_KEY	https://aistudio.google.com/apikey — 使用 Google 账号登录	是
QDRANT_URL	如果通过 Docker 在本地运行 Qdrant，则使用 http://localhost:6333（docker run -p 6333:6333 qdrant/qdrant）；也可以使用 https://cloud.qdrant.io 提供的免费集群 URL	是
LANGFUSE_SECRET_KEY / LANGFUSE_PUBLIC_KEY	https://cloud.langfuse.com — 免费套餐，创建项目后，从 Settings → API Keys 复制两个密钥	是
QDRANT_API_KEY	仅在使用 Qdrant Cloud 而非本地 Docker 时需要	否

没有 Docker，或想跳过 Qdrant 注册？请参阅下文运行 Qdrant中的说明。

2. 连接 Claude Desktop

将以下内容添加到 claude_desktop_config.json （Windows：%APPDATA%\Claude\claude_desktop_config.json，macOS：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "sec-intelligence-mcp": {
      "command": "uvx",
      "args": ["sec-intelligence-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key",
        "QDRANT_URL": "http://localhost:6333",
        "LANGFUSE_SECRET_KEY": "your-key",
        "LANGFUSE_PUBLIC_KEY": "your-key"
      }
    }
  }
}

重启 Claude Desktop，打开工具列表（锤子图标），确认其中出现 sec-intelligence-mcp，并带有 ping 工具。这样可以在提出实际问题前，先确认连接正常。

3. 试用

每次会话开始时，都要先摄取你想询问的公司的文件——这样会为其文件建立索引，以便搜索。之后只需用自然语言提问：

你： 摄取 NVIDIA 最近 2 份年度文件

Claude (调用 ingest_company_filings)：已为 NVIDIA 的 2 份文件建立索引——FY2024 的 10-K 包含 312 个文本块，FY2023 的包含 287 个。

你： 他们对出口管制风险说了什么？

Claude (调用 analyze_filing)：NVIDIA 的 FY2024 10-K 将出口管制法规列为主要风险：“美国政府已对我们的产品实施出口管制，并且未来可能进一步实施……对中国、香港和俄罗斯的限制已对我们的营收造成重大影响。” — [第 1A 项 — 风险因素]

你： 这与 AMD 相比如何？

Claude (调用 compare_companies)：[基于文件内容的并列回答，并分别引用两家公司的文件]

无需设计提示词，也无需特殊语法——Claude 会根据你的问题自动选择合适的工具。

---

🧰 可用工具

工具	功能	示例问题
ingest_company_filings	获取、解析并索引公司的近期 SEC 文件	“导入 NVIDIA 最近 3 份 10-K”
search_filings	对已导入的文件进行语义搜索，并返回带引文的段落	“在 Apple 的 10-K 中搜索有关 AI 投资的内容”
analyze_filing	针对特定问题给出有依据且附带引文的回答（RAG）	“Apple 在其 2024 年 10-K 中的主要风险因素是什么？”
get_filing_summary	对整份文件生成结构化执行摘要（业务、财务、MD&A、风险、展望）	“总结 NVIDIA 最新的 10-K”
compare_companies	针对特定方面并列比较 2-4 家公司，依据各公司的文件提供答案	“比较 NVIDIA 和 AMD 的 AI 芯片战略”
detect_financial_anomalies	标记公司 MD&A／风险披露中显著的同比变化	“NVIDIA 关于中国的风险表述在 2023 年至 2024 年间有变化吗？”
get_earnings_summary	从季度财报新闻稿（8-K）中提取关键指标、业绩指引和管理层评论	“总结 Apple 2024 年第二季度的财报”

🛠️ 技术栈

优先采用开源工具和免费套餐——端到端运行无需付费 API。

层级	工具	原因
MCP 协议	mcp Python SDK	Anthropic 官方 SDK
SEC 数据	SEC EDGAR Full-Text & Submissions API	官方、免费、无需 API 密钥
嵌入	sentence-transformers — intfloat/e5-base-v2	可在 CPU 上运行，无需 GPU
向量存储	Qdrant	免费自托管（Docker）或使用 Qdrant Cloud
本地缓存	DuckDB	股票代码查询、文件元数据、BM25 文本
关键词搜索	rank-bm25	与稠密搜索结合进行混合检索
重排序	sentence-transformers CrossEncoder（ms-marco-MiniLM-L-6-v2）	在大模型读取候选结果前重新评分
HTML／PDF 解析	beautifulsoup4、pdfplumber	将原始文件清理并转换为文本
大模型	Google Gemini（免费套餐）	生成答案
可观测性	LangFuse	追踪、跨度、忠实度评分
评估	RAGAS	自动评估忠实度／正确性／召回率
测试	pytest、pytest-asyncio	120 多项测试，完全模拟，无网络调用
代码检查	Ruff
CI/CD	GitHub Actions	每个 PR 都会执行代码检查、测试、Docker 构建和评估门禁
容器化	Docker + Docker Compose
部署	Oracle Cloud “Always Free” 套餐	真实持久磁盘，最高 24GB RAM，$0
打包	PyPI + uv/uvx、Hatchling	一条命令即可安装，无需克隆

🏗️ 架构

flowchart LR
    A[Claude Desktop / MCP client] -->|MCP tool calls| B[sec-intelligence-mcp server]
    B --> C[SEC EDGAR API]
    B --> D[Qdrant<br/>vector search]
    B --> E[Gemini<br/>answer generation]
    B --> F[LangFuse<br/>tracing + eval scores]
    C -->|filings| B
    D -->|cited passages| B
    E -->|grounded answer| B

📊 评估结果

使用 RAGAS 对 5 家公司的 50 组人工核验问题／真实答案进行评估（完整方法和原始结果见 eval/README.md）：

检索策略	忠实度	正确性	上下文召回率
v1：仅语义搜索（稠密嵌入）	0.92	0.67	0.84
v2：混合搜索（BM25 + 通过 RRF 进行语义搜索）— 生产环境默认设置	0.95	0.78	0.99
v3：混合搜索 + CrossEncoder 重排序	0.98	0.82	1.00

CI 的评估门禁会阻止任何将忠实度降至 0.75 以下的 PR 合入 main；评估使用这些问题中实际导入的实时数据子集——详见 .github/workflows/ci.yml。

LangFuse 仪表板

analyze_filing 回答“英伟达面临哪些出口管制风险？”的真实追踪记录——跨度树显示，retrieval 和 embedding 嵌套在工具调用下方，与大模型生成并列，同时自动附加了 faithfulness: 1.00 评分：

---

👩‍💻 面向开发者

想从源代码运行、参与贡献，或选择可自托管，而不是使用已发布的软件包？

启动 Qdrant

最简单的方法是使用 Docker：docker run -p 6333:6333 qdrant/qdrant。没有 Docker？也可以使用免费的 Qdrant Cloud 集群，并设置 QDRANT_API_KEY。

从本地克隆运行

1. 安装 uv。
2. 克隆仓库并安装依赖项：

   git clone https://github.com/jahanv01/sec-intelligence-mcp.git
   cd sec-intelligence-mcp
   uv sync
   

3. 将 .env.example 复制为 .env，并填写上表中的密钥。
4. 在本地启动 Qdrant：

   docker compose up -d qdrant
   

5. 直接运行服务：

   uv run python src/server.py
   

   或使用 MCP Inspector（开发 UI，需要 Node.js）：

   uv run mcp dev src/server.py
   

对于 Claude Desktop，请将其指向你的克隆版本，而不是已发布的软件包：

{
  "mcpServers": {
    "sec-intelligence-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\ABSOLUTE\\PATH\\TO\\sec-intelligence-mcp",
        "run",
        "python",
        "src/server.py"
      ]
    }
  }
}

如果缺少任何必需密钥，src/config.py 会在导入时立即失败（引发 RuntimeError）。

通过 Docker 运行

docker compose up -d 会构建服务镜像，并与 Qdrant 一起启动。app 服务通过 env_file 从本地 .env 读取密钥；QDRANT_URL 会覆盖为 http://qdrant:6333（网络内的服务名称），因为容器内的 localhost 无法连接到 qdrant 容器。

本地测试

uv run python -c "import mcp"                    # SDK installed correctly
uv run python scripts/test_server_stdio.py        # server responds over stdio (ping -> pong)
docker compose up -d qdrant
uv run python scripts/test_qdrant.py               # Qdrant round-trip works

# EDGAR data layer (each hits the real EDGAR API)
uv run python scripts/test_edgar_lookup.py         # ticker -> CIK, DuckDB-cached
uv run python scripts/test_edgar_filings.py        # recent 10-K filings for a ticker
uv run python scripts/test_edgar_parser.py         # download + clean a real filing
uv run python scripts/test_edgar_sections.py       # section detection + metadata

# Embedding & retrieval pipeline (real model + real Qdrant)
uv run python scripts/test_chunker.py              # section/paragraph chunking
uv run python scripts/test_encoder.py              # E5 embedding shape/latency
uv run python scripts/test_ingest.py               # chunk -> embed -> upsert to Qdrant
uv run python scripts/test_search.py               # semantic search with citations

# MCP tools (real pipeline + real Gemini calls)
uv run python scripts/test_tool_ingest_company_filings.py
uv run python scripts/test_tool_search_filings.py
uv run python scripts/test_tool_analyze_filing.py
uv run python scripts/test_tool_get_filing_summary.py

# Full mocked suite (no network calls)
uv run pytest tests/ -m "not integration"

项目结构

src/
├── server.py         # MCP server entrypoint
├── tools/             # One file per MCP tool
├── edgar/             # SEC EDGAR fetching + parsing
├── embeddings/        # Chunking + embedding pipeline
├── retrieval/         # Qdrant client + search + hybrid + rerank
├── evaluation/         # RAGAS eval pipeline
└── config.py          # Env var loading (fail-fast)
tests/                  # Unit/integration tests
prompts/                # Prompt templates (.txt)
data/                   # Gitignored local cache (DuckDB, filing PDFs, Qdrant storage)
eval/                   # Test questions + ground truth answers
scripts/                # One-off dev/test scripts

部署你自己的实例

通过 Claude Desktop 个人使用时，已发布的 PyPI 软件包就足够了——只有在需要独立且可公开访问的服务（例如供远程 MCP 客户端使用）时，才需要进行以下部署。

部署在 Oracle Cloud“Always Free”计算虚拟机（Ampere A1，ARM）上，而不是 Render 或 Hugging Face Spaces：这两个平台都会为容器提供临时文件系统（每次重启或重新部署都会清空），并将免费套餐的 RAM 限制在 512MB；这不足以让嵌入模型（e5-base-v2，仅 CPU，加载后约 440MB）与进程的其余部分舒适地共存。真正的 Always Free 虚拟机没有这两项限制——拥有真正的持久磁盘和最高 24GB RAM——因此 Qdrant 会使用本地开发时相同的 docker-compose.yml 在本地运行，无需单独注册 Qdrant Cloud 账户。

一次性设置：

1. 在 Oracle Cloud 控制台中创建一台 Always Free Ampere A1 计算实例（Ubuntu 镜像），并记下其公网 IP。
2. 在 VCN 的安全列表中（不只是实例自身的防火墙——两者都必须允许该端口），添加允许 TCP 端口 8000 的入站规则（以及用于 SSH 的 22，通常已开放）。
3. SSH 登录，安装 Docker 和 Compose 插件，然后：

   git clone https://github.com/jahanv01/sec-intelligence-mcp.git
   cd sec-intelligence-mcp
   cp .env.example .env   # fill in GEMINI_API_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_PUBLIC_KEY
   echo "MCP_TRANSPORT=sse" >> .env
   sudo docker compose up -d --build
   

   此处无需在 .env 中设置 QDRANT_URL——docker-compose.yml 已将其覆盖为 http://qdrant:6333，即网络内的服务名称，供 app 服务使用。
4. 还需在实例自身的防火墙中开放该端口（即使安全列表已允许，Ubuntu 自带的 iptables/ufw 规则仍会阻止该端口）：

   sudo iptables -I INPUT -p tcp --dport 8000 -j ACCEPT
   sudo netfilter-persistent save   # or: sudo ufw allow 8000/tcp
   

5. 验证：curl http://<instance-public-ip>:8000/health 返回 ok。

两个服务都设置了 restart: unless-stopped，因此虚拟机重启后，整个服务栈会自动恢复，无需手动操作。目前使用的是普通 HTTP（无 TLS/域名）——演示场景没问题，但实际生产部署应在前面配置 Caddy 或 Nginx，以支持 HTTPS。

替代方案：Hugging Face Spaces。 也可以使用 Docker SDK 实现，但需使用 Qdrant Cloud，而不是本地容器（Spaces 的存储会在重启时清空，不像真正的虚拟机）。打开 huggingface.co → New Space → SDK: Docker → 在 Space Settings 中将 GEMINI_API_KEY、QDRANT_URL、QDRANT_API_KEY、LANGFUSE_SECRET_KEY、LANGFUSE_PUBLIC_KEY 添加为密钥，并将 MCP_TRANSPORT=sse 添加为变量，然后将此仓库 git push 到 Space 的 git 远程仓库。

🤝 贡献

欢迎提交 Issue 和 PR。修改检索流水线前，请参阅 docs/edgar-api.md，了解 EDGAR API 的特殊要求（速率限制、必需的 User-Agent 标头），以及 eval/README.md；如果 PR 导致 RAGAS 忠实度降至 0.75 以下，将无法通过 CI 的 eval-gate 作业。