FilingsMCP 📈

Turn official BSE (Bombay Stock Exchange) filings into clean, AI-ready Markdown for Claude and Cursor.

Drop a financial PDF into an LLM, and it usually chokes—tables collapse, scanned pages become blank, and the model burns tokens on layout garbage. FilingsMCP fixes the input. It fetches filings directly from BSE, converts text-based PDFs into structured Markdown, and exposes them via a Model Context Protocol (MCP) server so your AI can read, search, and analyze them natively.

✨ Key Features

• AI-Ready Markdown Conversion: Transforms complex PDF layouts into clean, structured Markdown. Strips running headers/footers, removes mojibake (garbled text from subset fonts), and explicitly flags scanned-image PDFs so your AI never hallucinates from layout noise.
• Rich Provenance Frontmatter: Every generated .md file includes YAML frontmatter (headline, date, category, source_pdf, news_id, extraction_status), giving the AI strict context and citable sources.
• Deep Historical Data: Pulls from both the BSE announcements feed and the annual report archive, fetching filings going back to 1997 (including for delisted companies).
• Structured & Indexed Library: Files are organized systematically: <TICKER>/<category>/<YYYY>/<file>.pdf alongside its .md sibling. Automatically generates per-company and master INDEX.md files for easy navigation.
• Smart Deduplication & Atomic Writes: Merges overlapping sources without downloading duplicates. Writes files atomically—meaning an interrupted download never leaves a half-written, corrupted file in your library.
• Cloud-Ready MCP: Deploys to Render (or any cloud) in seconds via SSE, allowing multiple AI clients to query a single hosted library.

---

🚀 Out-of-the-Box Use Cases

Because the data is structured cleanly with frontmatter and categorized indexes, your AI agent can perform deep, multi-document analysis immediately:

1. Multi-Year Earnings Call (Concall) Synthesis

Prompt: "Read the last 3 years of concall transcripts for TANLA. Has management's guidance on EBITDA margins been accurate? Cite the specific dates and quotes."

• How it works: The AI uses search_filings to pull the concall .md files, reads the clean text, and cross-references guidance across years without hallucinating numbers.

2. Moat & Business Model Analysis

Prompt: "Analyze Reliance Industries' annual reports from 2015 to 2023. Identify changes in their revenue mix (Retail vs Jio vs O2C) and summarize the core moat."

• How it works: The AI pulls the annual-reports category, reads the structured markdown, and extracts tabular revenue data that would normally be destroyed by standard PDF parsing.

3. Automated Due Diligence Reports

Prompt: "Pull the last 5 years of financial results and investor presentations for Escorts Kubota. Draft a cited HTML report on their unit economics and tractor segment trajectory."

• How it works: The AI pulls the exact filings using the MCP tools, reads the provenance frontmatter to ensure it's looking at the right years, and generates a report with citations linking back to the source PDFs.

4. Board Action & Dividend Tracking

Prompt: "List all dividend declarations and board meeting outcomes for TITAN in the last 2 years."

• How it works: The AI filters by the corp-actions and board-meetings categories, extracting exact record dates and payout amounts from the clean Markdown.

---

🏗️ How It Works

1. Fetch & Resolve: You tell the AI to pull a company (e.g., "Pull TANLA"). The MCP server resolves the scrip code against BSE's live API.
2. Download & Convert: The engine downloads the PDFs, extracts the text, cleans the garbage, and atomically writes .pdf and .md siblings to the disk.
3. Index: A master INDEX.md and per-company INDEX.md are generated.
4. Query: Your AI agent uses the MCP tools (search_filings, read_filing) to navigate the clean Markdown library.

---

☁️ Deployment (Render)

This project includes a render.yaml Blueprint for one-click cloud deployment. A hosted MCP server allows you to query your library from anywhere without running a local Python server.

1. Push this repository to GitHub.
2. Go to Render and click New + → Blueprint.
3. Select your repository. Render will automatically detect the render.yaml.
4. Click Apply.
5. Render will provision a web service and attach a 10GB persistent disk (at /data) so your downloaded filings survive restarts.

Once deployed, Render will provide a URL (e.g., https://filings-mcp-xyz.onrender.com).

---

🔌 Connecting to Claude Desktop / Cursor

Once your server is running (either locally or on Render), add it to your MCP client configuration.

For Cloud (Render SSE):

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

For Local Stdio:

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

---

🛠️ Available MCP Tools

When connected, your AI agent has access to the following tools:

Tool	Description
list_companies	Lists every company held in the local library with filing counts.
get_index	Reads a specific company's INDEX.md or the master index.
search_filings	Finds filings by title text, narrowed by ticker, category, or year. Returns paths.
read_filing	Reads the clean Markdown of a specific filing. Automatically maps .pdf to .md.
pull_company	Downloads a company's filings from BSE into the library. Will ask for clarification if a name is ambiguous.
refresh_company	Re-pulls an existing company to fetch new filings, honoring the original category choices.

---

💻 Local Development

If you prefer to run the engine locally:

# 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

---

📄 License

MIT License. Built for AI-driven financial research.