FilingsMCP 📈

将官方 BSE (Bombay Stock Exchange) 申报文件转换为干净、AI 就绪的 Markdown，供 Claude 和 Cursor 使用。

将财务 PDF 丢给 LLM，它通常会卡壳——表格崩溃、扫描页面变成空白，模型把 token 浪费在布局垃圾上。FilingsMCP 修复了输入环节。它直接从 BSE 获取申报文件，将基于文本的 PDF 转换为结构化的 Markdown，并通过 Model Context Protocol (MCP) 服务器将其暴露出来，让你的 AI 能够原生地阅读、搜索和分析它们。

✨ 主要特性

• AI 就绪的 Markdown 转换： 将复杂的 PDF 布局转换为干净、结构化的 Markdown。去除页眉/页脚，移除 mojibake（子集字体产生的乱码文本），并明确标记扫描图像 PDF，让你的 AI 永远不会因布局噪声而产生幻觉。

• 丰富的来源 Frontmatter： 每个生成的 .md 文件都包含 YAML frontmatter（headline、date、category、source_pdf、news_id、extraction_status），为 AI 提供严格的上下文和可引用的来源。

• 深度历史数据： 同时从 BSE 公告源和年报存档中拉取，获取可追溯至 1997 年的申报文件（包括已退市公司的文件）。

• 结构化且带索引的文库： 文件按系统化方式组织：<TICKER>/<category>/<YYYY>/<file>.pdf 与其 .md 兄弟文件并列存放。自动生成每家公司及总体的 INDEX.md 文件，便于导航。

• 智能去重与原子写入： 合并重叠的来源，不下载重复文件。以原子方式写入文件——这意味着中断的下载绝不会在文库中留下写了一半的损坏文件。

• 云就绪的 MCP： 通过 SSE 在数秒内部署到 Render（或任何云平台），允许多个 AI 客户端查询同一个托管文库。

Related MCP server: sec-edgar-mcp

🚀 开箱即用的用例

由于数据通过 frontmatter 和分类索引进行了干净的结构化处理，你的 AI 代理可以立即执行深入的多文档分析：

1. 多年业绩电话会议（Concall）综合

提示词： “阅读 TANLA 过去 3 年的 concall 文字记录。管理层关于 EBITDA 利润率的指引是否准确？请引用具体的日期和原话。”

• 工作原理： AI 使用 search_filings 拉取 concall 的 .md 文件，阅读干净的文本，并跨年份交叉对照指引，而不会对数字产生幻觉。

2. 护城河与商业模式分析

提示词： “分析 Reliance Industries 2015 年至 2023 年的年报。识别其收入结构（Retail vs Jio vs O2C）的变化，并总结核心护城河。”

• 工作原理： AI 拉取 annual-reports 类别，阅读结构化的 markdown，并提取表格化的收入数据——这些数据通常会被标准 PDF 解析破坏。

3. 自动化尽职调查报告

提示词： “拉取 Escorts Kubota 过去 5 年的财务业绩和投资者演示文稿。起草一份带引用的 HTML 报告，说明其单位经济性和拖拉机业务板块的发展轨迹。”

• 工作原理： AI 使用 MCP 工具拉取确切的申报文件，读取来源 frontmatter 以确保查看的是正确的年份，并生成一份带引用的报告，引用链接回源 PDF。

4. 董事会行动与股息追踪

提示词： “列出 TITAN 过去 2 年所有股息公告和董事会会议结果。”

• 工作原理： AI 按 corp-actions 和 board-meetings 类别进行筛选，从干净的 Markdown 中提取准确的股权登记日和派息金额。

🏗️ 工作原理

1. 获取与解析： 你告诉 AI 拉取一家公司（例如“拉取 TANLA”）。MCP 服务器通过 BSE 的实时 API 解析证券代码。

2. 下载与转换： 引擎下载 PDF，提取文本，清理垃圾内容，并以原子方式将 .pdf 和 .md 兄弟文件写入磁盘。

3. 索引： 生成总体的 INDEX.md 和每家公司的 INDEX.md。

4. 查询： 你的 AI 代理使用 MCP 工具（search_filings、read_filing）浏览干净的 Markdown 文库。

☁️ 部署（Render）

本项目包含一个 render.yaml Blueprint（蓝图），用于一键云部署。托管的 MCP 服务器允许你从任何地方查询文库，而无需运行本地 Python 服务器。

1. 将此仓库推送到 GitHub。

2. 前往 Render，点击 New + → Blueprint。

3. 选择你的仓库。Render 将自动检测 render.yaml。

4. 点击 Apply。

5. Render 将配置一个 Web 服务并挂载一个 10GB 的持久化磁盘（位于 /data），这样你下载的申报文件在重启后依然存在。

部署完成后，Render 将提供一个 URL（例如 https://filings-mcp-xyz.onrender.com）。

🔌 连接到 Claude Desktop / Cursor

服务器运行后（无论是在本地还是在 Render 上），将其添加到你的 MCP 客户端配置中。

对于云（Render SSE）：

{
  "mcpServers": {
    "filings-mcp": {
      "url": "https://your-render-url.onrender.com/sse"
    }
  }
}

对于本地 Stdio：

{
  "mcpServers": {
    "filings-mcp": {
      "command": "filings-mcp",
      "args": ["--root", "~/FilingsLibrary"]
    }
  }
}

🛠️ 可用的 MCP 工具

连接后，你的 AI 代理可以访问以下工具：

💻 本地开发

如果你更倾向于在本地运行引擎：

# Clone the repo
git clone https://github.com/sathanandhh/filingsmcp.git
cd filingsmcp

# Set up Python 3.11+
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[mcp]"

# Run the MCP server (defaults to ~/FilingsLibrary)
filings-mcp --root ./MyLibrary

📄 许可证

MIT License。为 AI 驱动的金融研究而构建。