# SEC EDGAR MCP Server

A Model Context Protocol (MCP) server that exposes endpoints to retrieve SEC company profiles, historic filing listings, and structured XBRL financial statements directly into AI environments. Built with Python, FastMCP, and `edgartools`.

---

## ⚙️ Configuration & Setup

1. **Clone the Repository**:
   ```bash
   git clone https://github.com/MakAcp/sec-insight-mcp.git
   cd sec-insight-mcp
   ```

2. **Create and Activate Virtual Environment**:
   * **Windows**:
     ```powershell
     python -m venv .venv
     .\.venv\Scripts\activate
     ```
   * **macOS/Linux**:
     ```bash
     python3 -m venv .venv
     source .venv/bin/activate
     ```

3. **Install Dependencies**:
   Install the project in editable mode so dependencies listed in `pyproject.toml` are correctly resolved:
   ```bash
   pip install -e .
   ```

4. **Configure Environment**:
   Create a `.env` file in the root directory (refer to `.env.example`):
   ```ini
   SEC_EDGAR_USER_AGENT="YourName (your.email@example.com)"
   ```
   *Note: SEC compliance requires a valid name and email address in the User-Agent header. Program requests will be blocked if this is not provided.*

---

## 🛠️ Run & Test

* **Run the MCP Server (Stdio Mode)**:
   * **Windows**:
     ```powershell
     .\.venv\Scripts\python server.py
     ```
   * **macOS/Linux**:
     ```bash
     python server.py
     ```

* **Run the Automated Test Suite**:
   * **Windows**:
     ```powershell
     .\.venv\Scripts\python tests/run_tests.py
     ```
   * **macOS/Linux**:
     ```bash
     python tests/run_tests.py
     ```

---

## 📖 MCP Tools Legend

Below are the tool endpoints exposed by the server for integration with Cursor, Claude Desktop, or other MCP clients:

### 1. `health_check`
Perform a connection and compliance check on the server.
* **Parameters**: None
* **Returns**: `str` (Confirmation message containing the active SEC User-Agent).

### 2. `get_company_profile`
Retrieve administrative and registration metadata for a target company.
* **Parameters**:
  * `ticker_or_cik` (required, `str`): The company's ticker symbol (e.g. `AAPL`, `SOFI`) or 10-digit CIK (e.g. `0000320193`).
* **Returns**: `str` (Markdown profile table containing Official Name, CIK, Tickers, Industry SIC, shares outstanding, filer category, and addresses).

### 3. `list_filings`
Search and list recent filings submitted by a company. Supports row-based pagination (capped at max 20 pages / 2,000 filings to prevent infinite iteration loops).
* **Parameters**:
  * `ticker_or_cik` (required, `str`): The ticker symbol or CIK.
  * `form` (optional, `str`): Filter by form type (e.g. `10-K`, `10-Q`, `8-K`, `4`). Defaults to no filter.
  * `limit` (optional, `int`): Max number of filings per page to return (default: `10`, max: `100`).
  * `page` (optional, `int`): Page number to retrieve (default: `1`, max safety cap: `20`).
  * `year` (optional, `int`): Filter by filing calendar year.
* **Returns**: `str` (Markdown table listing Accession Numbers, Dates, Forms, Period of Report, formatted File Sizes, and XBRL structures with pagination metadata).

### 4. `get_financial_statements`
Extract the Consolidated Balance Sheets, Income Statements (Operations), and Cash Flow Statements from a company's XBRL report.
* **Parameters**:
  * `ticker_or_cik` (optional, `str`): The ticker or CIK. If provided alone, extracts statements from the **latest** report.
  * `accession_number` (optional, `str`): Specific 20-character accession number (e.g., `0000320193-25-000079`). If provided, extracts statements from that specific filing.
* **Returns**: `str` (Concatenated Markdown sheets detailing account lines, values, and comparative periods).

### 5. `get_filing_section`
Extract a specific text section (e.g. Item 1A Risk Factors, Item 7 MD&A, Item 1 Business Overview) from a target filing, supporting character chunk-based pagination (capped at max 10 pages / 120,000 characters to prevent infinite iteration loops).
* **Parameters**:
  * `ticker_or_cik` (optional, `str`): The ticker or CIK. If provided alone, extracts section from the **latest** 10-K or 10-Q filing.
  * `accession_number` (optional, `str`): Specific 20-character accession number.
  * `section_name` (optional, `str`): The name/ID of the section to retrieve (e.g., `Item 1A`, `Item 7`, `Item 1`). Defaults to `Item 1A`.
  * `page` (optional, `int`): Page number of the text chunk to retrieve (default: `1`, max safety cap: `10`).
  * `page_size` (optional, `int`): Number of characters per page (default: `12000`, min: `1000`, max: `30000`).
* **Returns**: `str` (Markdown-formatted text section chunk, with pagination info banner).

---

## 📖 MCP Prompts Legend

Below are the custom prompt templates registered on the server for user invocation:

### 1. `compare_competitors`
Renders a structured plan to perform a side-by-side comparative analysis of two competing companies.
* **Parameters**:
  * `ticker_a` (required, `str`): The first company's ticker symbol.
  * `ticker_b` (required, `str`): The second company's ticker symbol.
* **Flow**: Instructs the client model to retrieve profiles, Business Overviews (Item 1), and financial statements for both companies, compiling a comparative markdown table covering segment overlay, revenue, strategic advantages, and leverage.

### 2. `audit_investment_risks`
Directs the client model to act as a Senior Risk Analyst and perform a comprehensive risk and financial health audit on a target company.
* **Parameters**:
  * `ticker` (required, `str`): The company's ticker symbol.
* **Flow**: Instructs the model to retrieve the company's profile, Item 1A Risk Factors, and financial statements to output an Executive Summary risk assessment, top 3 operational hazards, financial health check, and management-to-balance-sheet red flags evaluation.

### 3. `analyze_earnings_quality_ttm`
Directs the client model to act as a Forensic Accountant and audit the quality of earnings of a company over the Trailing Twelve Months (TTM).
* **Parameters**:
  * `ticker` (required, `str`): The company's ticker symbol.
* **Flow**: Instructs the model to retrieve the company's quarterly financial statements, extract Net Income and Operating Cash Flow (OCF) for the last 4 available quarters, calculate the TTM totals and the TTM Quality of Earnings Ratio (`TTM OCF / TTM Net Income`), and analyze working capital drivers/non-cash items causing gaps.

---

## 🔌 Client Integration

### 1. Claude Desktop
Add the following configuration to your `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "sec-edgar": {
      "command": "/path/to/your/project/.venv/bin/python",
      "args": [
        "/path/to/your/project/server.py"
      ],
      "env": {
        "SEC_EDGAR_USER_AGENT": "YourName (your.email@example.com)"
      }
    }
  }
}
```
*(On Windows, use backslashes for paths and point to `Scripts\python.exe` instead of `bin/python`)*

### 2. Cursor
To configure the server in **Cursor Settings**:
1. Go to **Settings** -> **Features** -> **MCP**.
2. Click **+ Add New MCP Server**.
3. Fill in the details:
   - **Name**: `sec-edgar`
   - **Type**: `command`
   - **Command**: `/path/to/your/project/.venv/bin/python /path/to/your/project/server.py` *(or local Windows equivalent path)*
4. Click **Save**.

### 3. Codex
Add the following configuration to your global Codex configuration file (located at `%USERPROFILE%\.codex\config.toml` on Windows) or to the local project-specific `.codex/config.toml` file:

```toml
[mcp_servers.sec-edgar]
command = "/path/to/your/project/.venv/bin/python"
args = ["/path/to/your/project/server.py"]
env = { SEC_EDGAR_USER_AGENT = "YourName (your.email@example.com)" }
```