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:

   git clone https://github.com/MakAcp/sec-insight-mcp.git
   cd sec-insight-mcp
   

2. Create and Activate Virtual Environment:

   • Windows:

     python -m venv .venv
     .\.venv\Scripts\activate
     

   • macOS/Linux:

     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:

   pip install -e .
   

4. Configure Environment: Create a .env file in the root directory (refer to .env.example):

   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:

    .\.venv\Scripts\python server.py
    

  • macOS/Linux:

    python server.py
    

• Run the Automated Test Suite:

  • Windows:

    .\.venv\Scripts\python tests/run_tests.py
    

  • macOS/Linux:

    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):

{
  "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:

[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)" }