# Authors & Contributors
Source: https://sec-edgar-mcp.amorelli.tech/authors

Meet the people behind SEC Edgar MCP

# Authors & Contributors

SEC Edgar MCP is built and maintained by a dedicated team of developers and contributors from around the world.

## Core Team

<CardGroup>
  <Card title="Stefano Amorelli" icon="user" href="mailto:stefano@amorelli.tech">
    **Project Creator & Lead Maintainer**

    📧 [stefano@amorelli.tech](mailto:stefano@amorelli.tech)
  </Card>
</CardGroup>

## Contributors

We're grateful to all the contributors who have helped make SEC Edgar MCP better:

<CardGroup>
  <Card title="Harin Lee" icon="code" href="https://github.com/harinlee83">
    **Contributor**

    🔗 [GitHub](https://github.com/harinlee83)\
    📧 [harinlee83@gmail.com](mailto:harinlee83@gmail.com)
  </Card>

  <Card title="Davide Rutigliano" icon="code" href="https://github.com/DavideRutigliano">
    **Contributor**

    🔗 [GitHub](https://github.com/DavideRutigliano)
  </Card>

  <Card title="JC (Jonathan Chen)" icon="code" href="https://github.com/dijonkitchen">
    **Contributor**

    🔗 [GitHub](https://github.com/dijonkitchen)\
    📧 [jc@dijonkitchen.org](mailto:jc@dijonkitchen.org)
  </Card>

  <Card title="Scott Goley" icon="code" href="https://github.com/sgoley">
    **Contributor**

    🔗 [GitHub](https://github.com/sgoley)\
    📧 [scottmgoley@gmail.com](mailto:scottmgoley@gmail.com)
  </Card>

  <Card title="GERWARIC" icon="code" href="https://github.com/gerwaric">
    **Contributor**

    🔗 [GitHub](https://github.com/gerwaric)\
    📧 [gerwaric@gmail.com](mailto:gerwaric@gmail.com)
  </Card>
</CardGroup>

## How to Contribute

We welcome contributions from developers of all skill levels! There are many ways to contribute to SEC Edgar MCP:

### 🐛 Bug Reports

Found a bug? Please open an issue on our [GitHub repository](https://github.com/stefanoamorelli/sec-edgar-mcp) with:

* A clear description of the issue
* Steps to reproduce the problem
* Expected vs actual behavior
* Your environment details (Python version, OS, etc.)

### 💡 Feature Requests

Have an idea for a new feature? We'd love to hear it! Open an issue and describe:

* The problem you're trying to solve
* Your proposed solution
* Any alternative approaches you've considered

### 🔧 Code Contributions

Ready to contribute code? Here's how:

<Steps>
  <Step title="Fork the repository">
    Fork the [SEC Edgar MCP repository](https://github.com/stefanoamorelli/sec-edgar-mcp) to your GitHub account.
  </Step>

  <Step title="Clone your fork">
    ```bash theme={null}
    git clone https://github.com/your-username/sec-edgar-mcp.git
    cd sec-edgar-mcp
    ```
  </Step>

  <Step title="Create a feature branch">
    ```bash theme={null}
    git checkout -b feature/your-feature-name
    ```
  </Step>

  <Step title="Set up development environment">
    ```bash theme={null}
    python -m venv .venv
    source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate
    pip install -e ".[dev]"
    ```
  </Step>

  <Step title="Make your changes">
    Implement your feature or bug fix, following our coding standards.
  </Step>

  <Step title="Test your changes">
    ```bash theme={null}
    pytest
    mypy sec_edgar_mcp/
    ruff check .
    ```
  </Step>

  <Step title="Submit a pull request">
    Push your changes and create a pull request with a clear description.
  </Step>
</Steps>

### 📝 Documentation

Help improve our documentation by:

* Fixing typos or unclear explanations
* Adding examples and use cases
* Translating content
* Improving API documentation

### 💬 Community Support

Help other users by:

* Answering questions in GitHub discussions
* Sharing your use cases and examples
* Writing blog posts or tutorials

## Development Guidelines

When contributing code, please follow these guidelines:

### Code Style

* Use [Black](https://black.readthedocs.io/) for code formatting
* Follow [PEP 8](https://pep8.org/) style guidelines
* Use type hints for all functions and methods
* Write comprehensive docstrings

### Testing

* Write tests for new features and bug fixes
* Ensure all existing tests pass
* Aim for high test coverage
* Use descriptive test names

### Documentation

* Update documentation for any API changes
* Include docstrings for all public methods
* Add examples for new features
* Update the changelog

## Recognition

All contributors are recognized in our:

* [AUTHORS](https://github.com/stefanoamorelli/sec-edgar-mcp/blob/main/AUTHORS) file
* [CONTRIBUTORS](https://github.com/stefanoamorelli/sec-edgar-mcp/blob/main/CONTRIBUTORS) file
* Release notes and changelogs

## Acknowledgments

Special thanks to:

* **The SEC** for providing free access to EDGAR filings data
* **Anthropic** for the Model Context Protocol specification
* **All our users** who provide feedback and help improve the project

## Contact

Have questions about contributing? Reach out to:

* **Primary Contact:** Stefano Amorelli ([stefano@amorelli.tech](mailto:stefano@amorelli.tech))
* **GitHub Issues:** [Report issues or ask questions](https://github.com/stefanoamorelli/sec-edgar-mcp/issues)
* **Discussions:** [Join community discussions](https://github.com/stefanoamorelli/sec-edgar-mcp/discussions)

***

<Note>
  By contributing to SEC Edgar MCP, you agree that your contributions will be licensed under the same license as the project.
</Note>


# Architecture
Source: https://sec-edgar-mcp.amorelli.tech/concepts/architecture

SEC Edgar MCP system architecture and design

## System Overview

SEC Edgar MCP follows a modular architecture designed for reliability, performance, and maintainability.

## Core Components

### MCP Server Layer

* **Tool Registration**: Discovers and registers all available tools
* **Request Routing**: Routes requests to appropriate tool handlers
* **Response Formatting**: Ensures consistent JSON response format

### Data Access Layer

* **SEC API Client**: Handles SEC EDGAR REST API communication
* **XBRL Parser**: Direct parsing of XBRL filing content
* **Cache Manager**: Optimizes performance through intelligent caching

### Tool Implementation

* **Company Tools**: CIK lookup, company information, facts
* **Filing Tools**: Recent filings, content extraction, analysis
* **Financial Tools**: XBRL-based financial statement extraction
* **Insider Tools**: Form 3/4/5 transaction analysis


# Data Sources
Source: https://sec-edgar-mcp.amorelli.tech/concepts/data-sources

Understanding SEC EDGAR data sources and APIs

## Official SEC Data Sources

SEC Edgar MCP accesses multiple official SEC data sources:

### SEC EDGAR REST API

* **Company Facts**: `/api/xbrl/companyfacts/CIK{cik}.json`
* **Company Submissions**: `/api/xbrl/submissions/CIK{cik}.json`
* **Frames**: Aggregated XBRL data across companies

### Direct Filing Access

* **Filing Documents**: Individual SEC filing .txt files
* **XBRL Content**: Direct XBRL parsing from filing source

## Data Quality Guarantees

* **Real-time Access**: Direct from SEC systems
* **Exact Precision**: No rounding or approximation
* **Official Source**: Legally-binding filed documents
* **Verifiable**: All data includes SEC URL references


# MCP Protocol
Source: https://sec-edgar-mcp.amorelli.tech/concepts/mcp-protocol

Understanding the Model Context Protocol

## What is MCP?

The Model Context Protocol (MCP) is an open standard that enables seamless integration between LLM applications and external data sources and tools.

## How SEC Edgar MCP Uses MCP

SEC Edgar MCP implements the MCP protocol to provide:

* **Tool Discovery**: Automatic discovery of available SEC tools
* **Structured Responses**: JSON-formatted responses with exact data
* **Error Handling**: Consistent error reporting and recovery
* **Type Safety**: Well-defined schemas for all tool parameters

## MCP Architecture

```mermaid theme={null}
graph TD
    A[MCP Client] --> B[MCP Protocol]
    B --> C[SEC Edgar MCP Server]
    C --> D[SEC EDGAR API]
    C --> E[XBRL Parser]
```


# SEC EDGAR System
Source: https://sec-edgar-mcp.amorelli.tech/concepts/sec-edgar

Understanding the SEC EDGAR filing system and data sources

## What is SEC EDGAR?

EDGAR (Electronic Data Gathering, Analysis, and Retrieval) is the U.S. Securities and Exchange Commission's primary system for companies to submit official filings. It serves as the central repository for corporate financial information and "increases the efficiency, transparency, and fairness of the securities markets" by providing free public access to this data.

<Note>
  **Important**: EDGAR® and SEC® are trademarks of the U.S. Securities and Exchange Commission. SEC Edgar MCP is not affiliated with or approved by the U.S. Securities and Exchange Commission.
</Note>

## Key Filing Types

### Periodic Reports

<AccordionGroup>
  <Accordion title="Form 10-K (Annual Report)">
    **Purpose**: Comprehensive annual overview of the company's business and financial condition

    **Filing Deadline**:

    * Large accelerated filers: 60 days after fiscal year-end
    * Accelerated filers: 75 days after fiscal year-end
    * Non-accelerated filers: 90 days after fiscal year-end

    **Key Sections**:

    * Business overview and strategy
    * Risk factors
    * Financial statements and data
    * Management's Discussion and Analysis (MD\&A)

    **SEC Edgar MCP Tools**:

    * `get_recent_filings` with form\_type="10-K"
    * `get_filing_content` for full text
    * `get_financial_statements` for XBRL data
    * `get_filing_sections` for specific sections
  </Accordion>

  <Accordion title="Form 10-Q (Quarterly Report)">
    **Purpose**: Quarterly financial performance and position updates

    **Filing Deadline**: 40-45 days after quarter-end (varies by filer type)

    **Key Sections**:

    * Condensed financial statements
    * MD\&A for the quarter
    * Legal proceedings updates
    * Material changes in financial condition

    **SEC Edgar MCP Tools**:

    * `get_recent_filings` with form\_type="10-Q"
    * `get_financial_statements` for quarterly data
    * `get_xbrl_concepts` for specific metrics
  </Accordion>

  <Accordion title="Form 8-K (Current Report)">
    **Purpose**: Reports material events or corporate changes within 4 business days

    **Filing Deadline**: Within 4 business days of the triggering event

    **Common Items**:

    * Item 1.01: Material agreements
    * Item 2.02: Results of operations
    * Item 5.02: Officer/director changes
    * Item 7.01: Regulation FD disclosure
    * Item 8.01: Other events

    **SEC Edgar MCP Tools**:

    * `analyze_8k_filing` for detailed event analysis
    * `get_recent_filings` with form\_type="8-K"
  </Accordion>
</AccordionGroup>

### Proxy and Information Statements

<AccordionGroup>
  <Accordion title="DEF 14A (Proxy Statement)">
    **Purpose**: Information provided to shareholders before annual meetings

    **Key Information**:

    * Executive compensation details
    * Board of directors information
    * Shareholder proposals
    * Corporate governance matters

    **Timing**: Filed in advance of annual shareholder meetings
  </Accordion>
</AccordionGroup>

### Ownership and Insider Trading

<AccordionGroup>
  <Accordion title="Form 3 (Initial Statement of Ownership)">
    **Purpose**: Filed by new insiders within 10 days of becoming an insider

    **Who Files**: Officers, directors, and 10%+ shareholders

    **SEC Edgar MCP Tools**:

    * `get_insider_transactions`
    * `analyze_form_345`
  </Accordion>

  <Accordion title="Form 4 (Statement of Changes in Ownership)">
    **Purpose**: Reports changes in insider holdings

    **Filing Deadline**: Within 2 business days of the transaction

    **Transaction Types**:

    * Purchases and sales
    * Option exercises
    * Gifts and transfers
    * Stock awards and grants

    **SEC Edgar MCP Tools**:

    * `get_insider_transactions` for recent activity
    * `analyze_form_345` for detailed transaction analysis
  </Accordion>

  <Accordion title="Form 5 (Annual Statement of Ownership)">
    **Purpose**: Annual report of changes in ownership not previously reported

    **Filing Deadline**: 45 days after fiscal year-end

    **Covers**: Transactions that were exempt from Form 4 reporting
  </Accordion>
</AccordionGroup>

## XBRL: The Data Standard

### What is XBRL?

XBRL (eXtensible Business Reporting Language) is a standardized format for business and financial data that makes information machine-readable and comparable across companies.

<Tip>
  SEC Edgar MCP performs direct XBRL parsing to extract financial data with exact precision, maintaining the numeric accuracy as filed with the SEC.
</Tip>

### XBRL Namespaces

<CardGroup>
  <Card title="US-GAAP" icon="flag-usa">
    **US Generally Accepted Accounting Principles**

    Standard concepts like:

    * `us-gaap:Assets`
    * `us-gaap:Revenues`
    * `us-gaap:NetIncomeLoss`
  </Card>

  <Card title="Company-Specific" icon="building">
    **Company Extensions**

    Custom concepts for unique items:

    * `aapl:iPhoneRevenue`
    * `tsla:AutomotiveSales`
    * `msft:ProductivityRevenue`
  </Card>
</CardGroup>

### XBRL Structure

```xml theme={null}
<ix:nonFraction contextRef="Q32023" name="us-gaap:Revenues" unitRef="USD" 
                decimals="-6" scale="6">29900</ix:nonFraction>
```

**Components**:

* **Context**: Time period and entity information
* **Concept**: What is being measured (e.g., Revenue)
* **Unit**: Measurement unit (USD, shares, etc.)
* **Value**: The actual reported value
* **Scale**: Multiplication factor (scale="6" means multiply by 1,000,000)

## Data Quality and Precision

### SEC Edgar MCP's Approach

<CardGroup>
  <Card title="Direct Parsing" icon="magnifying-glass">
    Extracts data directly from XBRL using regex patterns, not API approximations
  </Card>

  <Card title="Exact Precision" icon="calculator">
    Maintains exact numeric precision with proper scale factors applied
  </Card>

  <Card title="Source Attribution" icon="link">
    Every response includes SEC URLs for independent verification
  </Card>
</CardGroup>

### Common Data Challenges

<AccordionGroup>
  <Accordion title="Scale Factors">
    **Problem**: XBRL values often use scale factors (e.g., scale="6" for millions)

    **SEC Edgar MCP Solution**: Automatically applies scale factors to provide actual values

    **Example**:

    * XBRL value: 29900 with scale="6"
    * Actual value: 29,900,000,000 (29.9 billion)
  </Accordion>

  <Accordion title="Context Periods">
    **Problem**: Same concept can have multiple values for different periods

    **SEC Edgar MCP Solution**: Provides period context and selects most recent values by default

    **Example**: Revenue for Q1, Q2, Q3, and annual periods all in same filing
  </Accordion>

  <Accordion title="Company Extensions">
    **Problem**: Companies create custom XBRL concepts not in standard taxonomies

    **SEC Edgar MCP Solution**: Discovers and extracts both standard and company-specific concepts

    **Example**: Apple's iPhone-specific revenue breakdowns
  </Accordion>
</AccordionGroup>

## Filing Lifecycle

### 1. Preparation Phase

* Companies prepare financial statements and disclosures
* XBRL tagging applied to financial data
* Legal and compliance review

### 2. Filing Submission

* Electronic submission through EDGAR system
* SEC assigns accession number (format: 0000320193-23-000064)
* Automatic validation checks

### 3. Public Availability

* **Immediate**: Filing appears in EDGAR database
* **Processing**: SEC systems index and process the data
* **API Access**: Data becomes available through SEC APIs

### 4. SEC Edgar MCP Access

* Real-time access to filed data
* Direct XBRL parsing for financial precision
* Structured tool responses with verification links

## Data Sources and APIs

### SEC EDGAR REST API

<CardGroup>
  <Card title="Company Facts" icon="chart-bar">
    **Endpoint**: `/api/xbrl/companyfacts/CIK{cik}.json`

    **Purpose**: Aggregated financial facts across all filings

    **SEC Edgar MCP Usage**: `get_company_facts`
  </Card>

  <Card title="Submissions" icon="file-text">
    **Endpoint**: `/api/xbrl/submissions/CIK{cik}.json`

    **Purpose**: Complete filing history and metadata

    **SEC Edgar MCP Usage**: `get_recent_filings`
  </Card>
</CardGroup>

### Direct Filing Access

```
https://www.sec.gov/Archives/edgar/data/{cik}/{accession-no-dashes}/{accession-no}.txt
```

**SEC Edgar MCP Usage**:

* `get_filing_content` for full text
* `get_xbrl_concepts` for direct XBRL parsing
* `analyze_8k_filing` for structured analysis

## Regulatory Context

### SEC Reporting Requirements

<Timeline>
  <TimelineItem title="1934 Securities Exchange Act">
    Established periodic reporting requirements for public companies
  </TimelineItem>

  <TimelineItem title="1996 EDGAR Mandate">
    Required electronic filing of most SEC documents
  </TimelineItem>

  <TimelineItem title="2009 XBRL Requirement">
    Mandated XBRL for financial statements in 10-K and 10-Q filings
  </TimelineItem>

  <TimelineItem title="2019 Inline XBRL">
    Required human-readable and machine-readable formats in single document
  </TimelineItem>
</Timeline>

### Compliance and Accuracy

<Warning>
  Public companies face significant penalties for inaccurate or late filings. SEC Edgar MCP provides access to this official, legally-binding financial data.
</Warning>

**Key Points**:

* **Legal Accuracy**: Filed data is subject to CEO/CFO certification
* **Audit Requirements**: Financial statements audited by independent firms
* **Real-time Updates**: 8-K filings provide timely disclosure of material events
* **Standardization**: XBRL enables consistent cross-company analysis

## Using SEC EDGAR Data Effectively

### Best Practices

<CardGroup>
  <Card title="Verify Sources" icon="shield-check">
    Always check SEC URLs provided in SEC Edgar MCP responses for independent verification
  </Card>

  <Card title="Understand Context" icon="lightbulb">
    Consider filing dates, periods, and any restatements when analyzing data
  </Card>

  <Card title="Compare Consistently" icon="scale-balanced">
    Use same periods and concepts when comparing companies
  </Card>

  <Card title="Read Disclosures" icon="book-open">
    Financial statements include important footnotes and disclosures
  </Card>
</CardGroup>

### Common Analysis Patterns

1. **Trend Analysis**: Compare same metrics across multiple periods
2. **Peer Comparison**: Analyze similar companies using consistent concepts
3. **Event Impact**: Use 8-K filings to understand material events
4. **Insider Activity**: Monitor Form 4 filings for insider sentiment

## Next Steps

<CardGroup>
  <Card title="MCP Protocol" icon="plug" href="/concepts/mcp-protocol">
    Learn how SEC Edgar MCP uses the Model Context Protocol
  </Card>

  <Card title="Tools Overview" icon="wrench" href="/tools/overview">
    Explore all available SEC Edgar MCP tools
  </Card>
</CardGroup>


# Installation
Source: https://sec-edgar-mcp.amorelli.tech/installation

Complete installation guide for SEC Edgar MCP

## System Requirements

<CardGroup>
  <Card title="Python" icon="python">
    **Version**: 3.11 or higher\
    **Required**: Yes
  </Card>

  <Card title="Docker" icon="docker">
    **Version**: Any recent version\
    **Required**: Optional but recommended
  </Card>

  <Card title="MCP Client" icon="plug">
    **Examples**: Claude Desktop, MCP CLI\
    **Required**: Yes
  </Card>
</CardGroup>

## Installation Methods

### Method 1: Docker (Recommended)

Docker provides the most reliable and consistent installation experience:

<Steps>
  <Step title="Install Docker">
    If you don't have Docker installed:

    <Tabs>
      <Tab title="Windows/Mac">
        Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop/)
      </Tab>

      <Tab title="Linux">
        ```bash theme={null}
        # Ubuntu/Debian
        sudo apt-get update
        sudo apt-get install docker.io

        # CentOS/RHEL
        sudo yum install docker

        # Start Docker service
        sudo systemctl start docker
        sudo systemctl enable docker
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Pull SEC Edgar MCP Image">
    ```bash theme={null}
    docker pull stefanoamorelli/sec-edgar-mcp:latest
    ```

    <Tip>
      The Docker image is automatically built and tested, ensuring consistency across all platforms.
    </Tip>
  </Step>

  <Step title="Verify Installation">
    Test the Docker image:

    ```bash theme={null}
    docker run --rm stefanoamorelli/sec-edgar-mcp:latest --version
    ```
  </Step>
</Steps>

### Method 2: Python Package (PyPI)

Install directly from Python Package Index:

<Steps>
  <Step title="Verify Python Version">
    ```bash theme={null}
    python --version
    # Should be 3.11 or higher
    ```
  </Step>

  <Step title="Create Virtual Environment (Recommended)">
    ```bash theme={null}
    python -m venv sec-edgar-env
    source sec-edgar-env/bin/activate  # On Windows: sec-edgar-env\Scripts\activate
    ```
  </Step>

  <Step title="Install Package">
    ```bash theme={null}
    pip install sec-edgar-mcp
    ```

    For development dependencies:

    ```bash theme={null}
    pip install sec-edgar-mcp[dev]
    ```
  </Step>

  <Step title="Verify Installation">
    ```bash theme={null}
    python -m sec_edgar_mcp.server --version
    ```
  </Step>
</Steps>

### Method 3: uvx (No Installation Required)

Run directly without installation using uvx:

<Steps>
  <Step title="Install uvx">
    If you don't have uvx installed:

    ```bash theme={null}
    pip install uvx
    # or
    pipx install uvx
    ```
  </Step>

  <Step title="Run SEC Edgar MCP">
    No installation needed - uvx will handle everything:

    ```bash theme={null}
    uvx --from git+https://github.com/stefanoamorelli/sec-edgar-mcp.git sec-edgar-mcp
    ```

    <Tip>
      uvx automatically manages package installation and updates, making it ideal for quick setup without managing Python environments.
    </Tip>
  </Step>

  <Step title="Configure MCP Client">
    Add to your MCP client configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "sec-edgar-mcp": {
          "command": "uvx",
          "args": [
            "--from",
            "git+https://github.com/stefanoamorelli/sec-edgar-mcp.git",
            "sec-edgar-mcp"
          ],
          "env": {
            "SEC_EDGAR_USER_AGENT": "Your Name (name@domain.com)"
          }
        }
      }
    }
    ```
  </Step>
</Steps>

### Method 4: Development Installation

For contributors and developers:

<Steps>
  <Step title="Clone Repository">
    ```bash theme={null}
    git clone https://github.com/stefanoamorelli/sec-edgar-mcp.git
    cd sec-edgar-mcp
    ```
  </Step>

  <Step title="Create Virtual Environment">
    ```bash theme={null}
    python -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate
    ```
  </Step>

  <Step title="Install in Development Mode">
    ```bash theme={null}
    pip install -e .[dev]
    ```
  </Step>

  <Step title="Run Tests">
    ```bash theme={null}
    python -m pytest tests/
    ```
  </Step>
</Steps>

## Configuration

### Environment Variables

<ParamField type="string">
  **Required**. Must include your name and email address.

  Example: `"John Doe (john@example.com)"`

  <Warning>
    The SEC requires this header and may block requests without proper identification.
  </Warning>
</ParamField>

<ParamField type="string">
  Directory for caching SEC data to improve performance.
</ParamField>

<ParamField type="integer">
  Requests per second limit to respect SEC API guidelines.
</ParamField>

### Setting Environment Variables

<Tabs>
  <Tab title="Linux/Mac">
    ```bash theme={null}
    export SEC_EDGAR_USER_AGENT="Your Name (name@domain.com)"
    export SEC_EDGAR_CACHE_DIR="~/sec-edgar-cache"
    ```

    Add to your shell profile (`~/.bashrc`, `~/.zshrc`) for persistence.
  </Tab>

  <Tab title="Windows">
    ```cmd theme={null}
    set SEC_EDGAR_USER_AGENT="Your Name (name@domain.com)"
    set SEC_EDGAR_CACHE_DIR="C:\sec-edgar-cache"
    ```

    Or use PowerShell:

    ```powershell theme={null}
    $env:SEC_EDGAR_USER_AGENT = "Your Name (name@domain.com)"
    ```
  </Tab>

  <Tab title="Docker">
    Pass environment variables to Docker:

    ```bash theme={null}
    docker run -e SEC_EDGAR_USER_AGENT="Your Name (name@domain.com)" \\
               -e SEC_EDGAR_CACHE_DIR="/cache" \\
               stefanoamorelli/sec-edgar-mcp:latest
    ```
  </Tab>
</Tabs>

## MCP Client Configuration

### Claude Desktop

Add to `~/.config/claude-desktop/config.json`:

<Tabs>
  <Tab title="Docker">
    ```json theme={null}
    {
      "mcpServers": {
        "sec-edgar-mcp": {
          "command": "docker",
          "args": [
            "run",
            "-i",
            "--rm",
            "-e",
            "SEC_EDGAR_USER_AGENT=Your Name (name@domain.com)",
            "stefanoamorelli/sec-edgar-mcp:latest"
          ],
          "env": {}
        }
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```json theme={null}
    {
      "mcpServers": {
        "sec-edgar-mcp": {
          "command": "python",
          "args": ["-m", "sec_edgar_mcp.server"],
          "env": {
            "SEC_EDGAR_USER_AGENT": "Your Name (name@domain.com)"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Other MCP Clients

The configuration format varies by client, but the core elements remain:

* **Command**: How to start the server (`docker run...` or `python -m...`)
* **Environment**: The `SEC_EDGAR_USER_AGENT` variable
* **Transport**: Usually stdio (default)

## Verification

### Test Connection

After installation and configuration:

1. **Restart your MCP client**
2. **Check for tool discovery** - You should see SEC Edgar tools available
3. **Try a simple query**: Ask for a company's recent filings

### Expected Tools

Your MCP client should discover these tool categories:

<CardGroup>
  <Card title="Company Tools" icon="building">
    * lookup\_company\_cik
    * get\_company\_info
    * get\_company\_facts
  </Card>

  <Card title="Filing Tools" icon="file-text">
    * get\_recent\_filings
    * get\_filing\_content
    * analyze\_8k\_filing
  </Card>

  <Card title="Financial Tools" icon="chart-bar">
    * get\_financial\_statements
    * extract\_financial\_data
  </Card>

  <Card title="Insider Tools" icon="user-tie">
    * get\_insider\_transactions
    * analyze\_form\_345
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Python Version Issues">
    SEC Edgar MCP requires Python 3.11+. Check your version:

    ```bash theme={null}
    python --version
    ```

    If you have multiple Python versions, you may need to use `python3.11` or similar.
  </Accordion>

  <Accordion title="Docker Permission Issues">
    On Linux, you may need to add your user to the docker group:

    ```bash theme={null}
    sudo usermod -aG docker $USER
    # Logout and login again
    ```
  </Accordion>

  <Accordion title="Package Installation Failures">
    Try updating pip and setuptools:

    ```bash theme={null}
    pip install --upgrade pip setuptools wheel
    pip install sec-edgar-mcp
    ```
  </Accordion>

  <Accordion title="MCP Client Not Finding Tools">
    * Verify the JSON configuration syntax
    * Check the MCP client logs
    * Ensure the server starts without errors
    * Restart the MCP client after configuration changes
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Get up and running with your first queries
  </Card>

  <Card title="Configuration" icon="gear" href="/setup/configuration">
    Advanced configuration and customization
  </Card>
</CardGroup>


# Introduction
Source: https://sec-edgar-mcp.amorelli.tech/introduction

SEC Edgar MCP - Connect AI models to comprehensive SEC EDGAR filings data

## Overview

SEC Edgar MCP is an open-source MCP (Model Context Protocol) server that connects AI models to the rich dataset of [SEC EDGAR filings](https://www.sec.gov/edgar). EDGAR (Electronic Data Gathering, Analysis, and Retrieval) is the U.S. SEC's primary system for companies to submit official filings, containing millions of filings that increase the efficiency, transparency, and fairness of securities markets.

<Note>
  **Important**: EDGAR® and SEC® are trademarks of the U.S. Securities and Exchange Commission. This open-source project is not affiliated with or approved by the U.S. Securities and Exchange Commission.
</Note>

## Key Features

<CardGroup>
  <Card title="Real-time SEC Data" icon="chart-line" href="/concepts/data-sources">
    Access live SEC EDGAR filings with exact precision and filing references
  </Card>

  <Card title="Comprehensive Tools" icon="wrench" href="/tools/overview">
    Complete set of tools for company lookup, filings, financials, and insider trading
  </Card>

  <Card title="XBRL Parsing" icon="code" href="/tools/financial/xbrl-parsing">
    Direct XBRL parsing for exact financial precision with no rounding
  </Card>

  <Card title="MCP Protocol" icon="plug" href="/concepts/mcp-protocol">
    Built on the open Model Context Protocol standard for seamless AI integration
  </Card>
</CardGroup>

## What You Can Do

With SEC Edgar MCP, AI assistants can:

* **Company Research**: Look up companies by name, ticker, or CIK number
* **Filing Analysis**: Access and analyze 10-K, 10-Q, 8-K, and other SEC filings
* **Financial Data**: Extract exact financial statements with XBRL precision
* **Insider Trading**: Monitor Form 3, 4, and 5 insider transaction filings
* **Due Diligence**: Comprehensive corporate transparency and compliance monitoring

<Tip>
  The server leverages the [sec-edgar-toolkit Python library](https://github.com/stefanoamorelli/sec-edgar-toolkit) to fetch data from official SEC sources and performs direct XBRL parsing for exact financial precision.
</Tip>

## Architecture Overview

The SEC Edgar MCP server acts as a bridge between AI clients and SEC EDGAR data:

```mermaid theme={null}
graph TD
    A[MCP Client/AI Assistant] --> B[SEC Edgar MCP Server]
    B --> C[sec-edgar-toolkit Library]
    B --> D[Direct XBRL Parser]
    C --> E[SEC EDGAR REST API]
    D --> F[SEC Filing Documents]
    E --> G[Official SEC Data]
    F --> G
```

## Getting Started

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get up and running in minutes with Docker or Python
  </Card>

  <Card title="Installation Guide" icon="download" href="/installation">
    Detailed installation instructions for all platforms
  </Card>
</CardGroup>

## Use Cases

<AccordionGroup>
  <Accordion title="Investment Research">
    Analyze company financials, compare metrics across companies, and track filing updates for investment decisions.
  </Accordion>

  <Accordion title="Financial Analysis">
    Extract precise financial data from 10-K and 10-Q filings, build financial models, and perform ratio analysis.
  </Accordion>

  <Accordion title="Compliance Monitoring">
    Monitor insider trading activities, track regulatory filings, and ensure compliance with SEC requirements.
  </Accordion>

  <Accordion title="Due Diligence">
    Comprehensive corporate research for M\&A, partnerships, or investment opportunities.
  </Accordion>
</AccordionGroup>

## Next Steps

Ready to get started? Follow our [Quickstart Guide](/quickstart) to set up SEC Edgar MCP in minutes, or explore our [Tools Reference](/tools/overview) to see what's possible.


# License
Source: https://sec-edgar-mcp.amorelli.tech/license

SEC Edgar MCP licensing information

# License

SEC Edgar MCP is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**.

## What does this mean?

The AGPL-3.0 is a strong copyleft license that ensures the software remains free and open source.

<CardGroup>
  <Card title="✅ You CAN" icon="check">
    * Use the software for any purpose
    * Study and modify the source code
    * Distribute original or modified versions
    * Use it in commercial applications
    * Access the source code
  </Card>

  <Card title="📋 You MUST" icon="list-check">
    * Include the original license and copyright
    * Provide source code for modifications
    * Share modifications under the same license
    * Provide network source if hosting modified versions
    * Document significant changes
  </Card>
</CardGroup>

## Commercial Licensing

For commercial licensing options or alternative licensing arrangements, please contact:

**📧 [stefano@amorelli.tech](mailto:stefano@amorelli.tech)**

## Full License Text

<Note>
  The complete AGPL-3.0 license text is available in the [LICENSE file](https://github.com/stefanoamorelli/sec-edgar-mcp/blob/main/LICENSE) in our repository.
</Note>

## Copyright Notice

```
SEC Edgar MCP - AI-powered SEC EDGAR data access
Copyright (C) 2024 Stefano Amorelli

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
```

***

<Warning>
  This page provides a summary of the AGPL-3.0 license for informational purposes. The [full license text](https://github.com/stefanoamorelli/sec-edgar-mcp/blob/main/LICENSE) is the authoritative legal document.
</Warning>


# Quickstart
Source: https://sec-edgar-mcp.amorelli.tech/quickstart

Get SEC Edgar MCP running in minutes

## Prerequisites

<CardGroup>
  <Card title="System Requirements" icon="computer">
    * Python 3.11 or higher
    * Docker (optional, but recommended)
    * MCP-compatible client (Claude Desktop, etc.)
  </Card>

  <Card title="SEC Requirements" icon="shield-check">
    * Valid User-Agent header for SEC API access
    * Email address for identification
  </Card>
</CardGroup>

## Installation Options

<Tabs>
  <Tab title="Docker (Recommended)">
    The fastest way to get started is using Docker:

    <Steps>
      <Step title="Pull the Docker image">
        ```bash theme={null}
        docker pull stefanoamorelli/sec-edgar-mcp:latest
        ```
      </Step>

      <Step title="Configure your MCP client">
        Add this to your MCP client configuration:

        ```json theme={null}
        {
          "mcpServers": {
            "sec-edgar-mcp": {
              "command": "docker",
              "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "SEC_EDGAR_USER_AGENT=Your Name (name@domain.com)",
                "stefanoamorelli/sec-edgar-mcp:latest"
              ],
              "env": {}
            }
          }
        }
        ```
      </Step>

      <Step title="Test the connection">
        Your MCP client should now discover the SEC Edgar tools automatically.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Python/pip">
    Install directly from PyPI:

    <Steps>
      <Step title="Install the package">
        ```bash theme={null}
        pip install sec-edgar-mcp
        ```
      </Step>

      <Step title="Set environment variable">
        ```bash theme={null}
        export SEC_EDGAR_USER_AGENT="Your Name (name@domain.com)"
        ```
      </Step>

      <Step title="Configure MCP client">
        ```json theme={null}
        {
          "mcpServers": {
            "sec-edgar-mcp": {
              "command": "python",
              "args": ["-m", "sec_edgar_mcp.server"],
              "env": {
                "SEC_EDGAR_USER_AGENT": "Your Name (name@domain.com)"
              }
            }
          }
        }
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="uvx">
    Run directly without installation using uvx:

    <Steps>
      <Step title="Configure MCP client">
        Add this to your MCP client configuration:

        ```json theme={null}
        {
          "mcpServers": {
            "sec-edgar-mcp": {
              "command": "uvx",
              "args": [
                "--from",
                "git+https://github.com/stefanoamorelli/sec-edgar-mcp.git",
                "sec-edgar-mcp"
              ],
              "env": {
                "SEC_EDGAR_USER_AGENT": "Your Name (name@domain.com)"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Test the connection">
        Your MCP client should now discover the SEC Edgar tools automatically.
      </Step>
    </Steps>

    <Note>
      uvx automatically handles package installation and updates, making it ideal for quick setup without managing Python environments.
    </Note>
  </Tab>
</Tabs>

<Warning>
  **Important**: You must provide a valid `SEC_EDGAR_USER_AGENT` that includes your name and email address. The SEC requires this for API access and may block requests without proper identification.
</Warning>

## First Steps

### 1. Verify Installation

Once configured, your MCP client should automatically discover these tools:

<CardGroup>
  <Card title="Company Tools" icon="building">
    * `lookup_company_cik`
    * `get_company_info`
    * `get_company_facts`
  </Card>

  <Card title="Filing Tools" icon="file-text">
    * `get_recent_filings`
    * `get_filing_content`
    * `analyze_8k_filing`
  </Card>

  <Card title="Financial Tools" icon="chart-bar">
    * `get_financial_statements`
    * `extract_financial_data`
  </Card>

  <Card title="Insider Tools" icon="user-tie">
    * `get_insider_transactions`
    * `analyze_form_345`
  </Card>
</CardGroup>

### 2. Try Your First Query

Ask your AI assistant:

<CodeGroup>
  ```text Example Query 1 theme={null}
  "What's Apple's latest 10-K filing?"
  ```

  ```text Example Query 2   theme={null}
  "Show me Tesla's revenue from their most recent quarterly report"
  ```

  ```text Example Query 3 theme={null}
  "Find insider transactions for Microsoft in the last 30 days"
  ```
</CodeGroup>

### 3. Explore the Tools

<Tip>
  Each tool includes comprehensive instructions to prevent AI hallucination and ensure responses are based only on actual SEC filing data with clickable verification links.
</Tip>

## Common MCP Clients

<Tabs>
  <Tab title="Claude Desktop">
    Add the configuration to `~/.config/claude-desktop/config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "sec-edgar-mcp": {
          "command": "docker",
          "args": [
            "run", "-i", "--rm",
            "-e", "SEC_EDGAR_USER_AGENT=Your Name (name@domain.com)",
            "stefanoamorelli/sec-edgar-mcp:latest"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other MCP Clients">
    Any MCP-compatible client can use SEC Edgar MCP. The configuration format may vary slightly, but the core setup remains the same:

    1. Specify the command to run the server
    2. Set the `SEC_EDGAR_USER_AGENT` environment variable
    3. The client will discover tools automatically via the MCP protocol
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Server not starting">
    * Verify Python 3.11+ is installed
    * Check that the `SEC_EDGAR_USER_AGENT` environment variable is set
    * Ensure Docker is running (if using Docker method)
  </Accordion>

  <Accordion title="Tools not discovered">
    * Restart your MCP client after adding the configuration
    * Check the client logs for connection errors
    * Verify the JSON configuration syntax is valid
  </Accordion>

  <Accordion title="SEC API errors">
    * Ensure your User-Agent includes a valid email address
    * Check your internet connection
    * The SEC may temporarily rate limit requests
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Explore Tools" icon="wrench" href="/tools/overview">
    Learn about all available SEC Edgar tools
  </Card>

  <Card title="Configuration" icon="gear" href="/setup/configuration">
    Advanced configuration options and settings
  </Card>

  <Card title="Use Cases" icon="lightbulb" href="/use-cases/financial-analysis">
    Real-world examples and use cases
  </Card>

  <Card title="Troubleshooting" icon="bug" href="/setup/troubleshooting">
    Solutions for common issues
  </Card>
</CardGroup>


# Configuration
Source: https://sec-edgar-mcp.amorelli.tech/setup/configuration

Advanced configuration options for SEC Edgar MCP

## Environment Variables

<ParamField type="string">
  **Required**. Must include your name and email address in the format: `"Your Name (email@domain.com)"`

  The SEC requires this header for all API requests and will block requests without proper identification.

  <CodeGroup>
    ```bash Linux/Mac theme={null}
    export SEC_EDGAR_USER_AGENT="John Doe (john@company.com)"
    ```

    ```cmd Windows (CMD) theme={null}
    set SEC_EDGAR_USER_AGENT="John Doe (john@company.com)"
    ```

    ```powershell Windows (PowerShell) theme={null}
    $env:SEC_EDGAR_USER_AGENT = "John Doe (john@company.com)"
    ```
  </CodeGroup>
</ParamField>

<ParamField type="string">
  Directory for caching SEC data to improve performance and reduce API calls.

  ```bash theme={null}
  export SEC_EDGAR_CACHE_DIR="/path/to/custom/cache"
  ```
</ParamField>

<ParamField type="integer">
  Requests per second limit. SEC allows up to 10 requests per second.

  ```bash theme={null}
  export SEC_EDGAR_RATE_LIMIT="8"  # Conservative limit
  ```
</ParamField>

<ParamField type="integer">
  Request timeout in seconds for SEC API calls.

  ```bash theme={null}
  export SEC_EDGAR_TIMEOUT="60"  # Longer timeout for large filings
  ```
</ParamField>

<ParamField type="boolean">
  Enable debug logging for troubleshooting.

  ```bash theme={null}
  export SEC_EDGAR_DEBUG="true"
  ```
</ParamField>

## MCP Client Configuration

### Claude Desktop

Configure Claude Desktop by editing `~/.config/claude-desktop/config.json`:

<Tabs>
  <Tab title="Docker Configuration">
    ```json theme={null}
    {
      "mcpServers": {
        "sec-edgar-mcp": {
          "command": "docker",
          "args": [
            "run",
            "-i",
            "--rm",
            "-e", "SEC_EDGAR_USER_AGENT=Your Name (name@domain.com)",
            "-e", "SEC_EDGAR_CACHE_DIR=/cache",
            "-e", "SEC_EDGAR_RATE_LIMIT=8",
            "-v", "/home/user/.cache/sec-edgar:/cache",
            "stefanoamorelli/sec-edgar-mcp:latest"
          ],
          "env": {}
        }
      }
    }
    ```
  </Tab>

  <Tab title="Python Configuration">
    ```json theme={null}
    {
      "mcpServers": {
        "sec-edgar-mcp": {
          "command": "python",
          "args": ["-m", "sec_edgar_mcp.server"],
          "env": {
            "SEC_EDGAR_USER_AGENT": "Your Name (name@domain.com)",
            "SEC_EDGAR_CACHE_DIR": "/home/user/.cache/sec-edgar",
            "SEC_EDGAR_RATE_LIMIT": "8",
            "SEC_EDGAR_TIMEOUT": "60"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Other MCP Clients

For other MCP-compatible clients, adapt the configuration format but maintain these key elements:

<CardGroup>
  <Card title="Command" icon="terminal">
    How to start the server:

    * Docker: `docker run ...`
    * Python: `python -m sec_edgar_mcp.server`
  </Card>

  <Card title="Environment" icon="gear">
    Required environment variables:

    * `SEC_EDGAR_USER_AGENT`
    * Optional performance tuning vars
  </Card>
</CardGroup>

## Advanced Configuration

### Custom Cache Configuration

For production or high-volume usage, configure a persistent cache:

```bash theme={null}
# Create dedicated cache directory
mkdir -p /opt/sec-edgar-cache
chmod 755 /opt/sec-edgar-cache

# Set environment variable
export SEC_EDGAR_CACHE_DIR="/opt/sec-edgar-cache"
```

### Rate Limiting Strategy

<Tip>
  The SEC allows up to 10 requests per second, but being conservative can improve reliability:
</Tip>

```bash theme={null}
# Conservative rate limiting for production
export SEC_EDGAR_RATE_LIMIT="8"

# Aggressive rate limiting for development/testing
export SEC_EDGAR_RATE_LIMIT="5"
```

### Timeout Configuration

Adjust timeouts based on your use case:

```bash theme={null}
# Short timeout for interactive use
export SEC_EDGAR_TIMEOUT="30"

# Long timeout for large filing analysis
export SEC_EDGAR_TIMEOUT="120"

# Very long timeout for comprehensive analysis
export SEC_EDGAR_TIMEOUT="300"
```

## Docker-Specific Configuration

### Volume Mounting

Mount a persistent cache volume:

```bash theme={null}
docker run -i --rm \
  -e SEC_EDGAR_USER_AGENT="Your Name (name@domain.com)" \
  -v /host/cache/path:/cache \
  -e SEC_EDGAR_CACHE_DIR=/cache \
  stefanoamorelli/sec-edgar-mcp:latest
```

### Resource Limits

Set resource limits for production:

```bash theme={null}
docker run -i --rm \
  --memory="1g" \
  --cpus="2" \
  -e SEC_EDGAR_USER_AGENT="Your Name (name@domain.com)" \
  stefanoamorelli/sec-edgar-mcp:latest
```

### Network Configuration

For proxy or firewall environments:

```bash theme={null}
docker run -i --rm \
  --network=host \
  -e HTTP_PROXY="http://proxy.company.com:8080" \
  -e HTTPS_PROXY="http://proxy.company.com:8080" \
  -e SEC_EDGAR_USER_AGENT="Your Name (name@domain.com)" \
  stefanoamorelli/sec-edgar-mcp:latest
```

## Performance Tuning

### Memory Optimization

For memory-constrained environments:

```python theme={null}
# In your MCP client configuration
{
  "env": {
    "SEC_EDGAR_USER_AGENT": "Your Name (name@domain.com)",
    "SEC_EDGAR_CACHE_SIZE": "100",  # Limit cache entries
    "SEC_EDGAR_MEMORY_LIMIT": "512m"  # Memory limit
  }
}
```

### Concurrent Processing

Configure concurrent request handling:

```bash theme={null}
export SEC_EDGAR_MAX_WORKERS="4"  # Concurrent workers
export SEC_EDGAR_BATCH_SIZE="10"  # Batch size for bulk operations
```

## Security Configuration

### Network Security

<Warning>
  Ensure SEC Edgar MCP only communicates with authorized SEC endpoints.
</Warning>

```bash theme={null}
# Restrict outbound connections (firewall rules)
iptables -A OUTPUT -d sec.gov -p tcp --dport 443 -j ACCEPT
iptables -A OUTPUT -p tcp --dport 443 -j DROP
```

### User Agent Security

<Note>
  Never use fake or misleading User-Agent headers. The SEC requires accurate identification.
</Note>

```bash theme={null}
# Good - includes real contact information
export SEC_EDGAR_USER_AGENT="Company Analysis Tool - John Doe (john@company.com)"

# Bad - fake or misleading information
export SEC_EDGAR_USER_AGENT="Mozilla/5.0 Browser"
```

## Logging Configuration

### Enable Debug Logging

```bash theme={null}
export SEC_EDGAR_DEBUG="true"
export SEC_EDGAR_LOG_LEVEL="DEBUG"
export SEC_EDGAR_LOG_FILE="/var/log/sec-edgar-mcp.log"
```

### Structured Logging

For production environments:

```json theme={null}
{
  "env": {
    "SEC_EDGAR_LOG_FORMAT": "json",
    "SEC_EDGAR_LOG_LEVEL": "INFO",
    "SEC_EDGAR_LOG_FILE": "/var/log/sec-edgar-mcp.log"
  }
}
```

## Validation

### Configuration Validation

Test your configuration:

<Tabs>
  <Tab title="Docker">
    ```bash theme={null}
    docker run --rm \
      -e SEC_EDGAR_USER_AGENT="Your Name (name@domain.com)" \
      stefanoamorelli/sec-edgar-mcp:latest \
      --test-config
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    python -m sec_edgar_mcp.server --test-config
    ```
  </Tab>
</Tabs>

### Connection Testing

Verify SEC API connectivity:

```bash theme={null}
# Test basic connectivity
curl -H "User-Agent: Your Name (name@domain.com)" \
     "https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json"
```

## Troubleshooting Configuration

<AccordionGroup>
  <Accordion title="User-Agent Rejected">
    **Problem**: SEC API returns 403 Forbidden

    **Solution**: Ensure User-Agent includes valid email address:

    ```bash theme={null}
    export SEC_EDGAR_USER_AGENT="John Doe (john.doe@company.com)"
    ```
  </Accordion>

  <Accordion title="Rate Limiting Errors">
    **Problem**: Too many requests errors

    **Solution**: Reduce rate limit:

    ```bash theme={null}
    export SEC_EDGAR_RATE_LIMIT="5"
    ```
  </Accordion>

  <Accordion title="Cache Permission Issues">
    **Problem**: Cannot write to cache directory

    **Solution**: Fix permissions:

    ```bash theme={null}
    mkdir -p ~/.cache/sec-edgar
    chmod 755 ~/.cache/sec-edgar
    ```
  </Accordion>

  <Accordion title="Timeout Issues">
    **Problem**: Requests timing out

    **Solution**: Increase timeout:

    ```bash theme={null}
    export SEC_EDGAR_TIMEOUT="120"
    ```
  </Accordion>
</AccordionGroup>

## Configuration Examples

### Development Setup

```bash theme={null}
# Development configuration
export SEC_EDGAR_USER_AGENT="Dev Testing (developer@company.com)"
export SEC_EDGAR_RATE_LIMIT="5"
export SEC_EDGAR_DEBUG="true"
export SEC_EDGAR_CACHE_DIR="./dev-cache"
```

### Production Setup

```bash theme={null}
# Production configuration
export SEC_EDGAR_USER_AGENT="Production Analysis (ops@company.com)"
export SEC_EDGAR_RATE_LIMIT="8"
export SEC_EDGAR_TIMEOUT="60"
export SEC_EDGAR_CACHE_DIR="/opt/sec-edgar-cache"
export SEC_EDGAR_LOG_LEVEL="INFO"
export SEC_EDGAR_LOG_FILE="/var/log/sec-edgar.log"
```

### High-Volume Setup

```bash theme={null}
# High-volume configuration
export SEC_EDGAR_USER_AGENT="Batch Analysis (batch@company.com)"
export SEC_EDGAR_RATE_LIMIT="9"
export SEC_EDGAR_MAX_WORKERS="8"
export SEC_EDGAR_BATCH_SIZE="20"
export SEC_EDGAR_CACHE_SIZE="1000"
```


# Docker Setup
Source: https://sec-edgar-mcp.amorelli.tech/setup/docker

Running SEC Edgar MCP with Docker

## Docker Installation

Docker provides the most reliable and consistent way to run SEC Edgar MCP across different platforms.

## Quick Start

```bash theme={null}
docker pull stefanoamorelli/sec-edgar-mcp:latest
```

## Configuration

Add to your MCP client configuration:

```json theme={null}
{
  "mcpServers": {
    "sec-edgar-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SEC_EDGAR_USER_AGENT=Your Name (name@domain.com)",
        "stefanoamorelli/sec-edgar-mcp:latest"
      ]
    }
  }
}
```


# MCP Clients
Source: https://sec-edgar-mcp.amorelli.tech/setup/mcp-clients

Compatible MCP clients and configuration guides

# MCP Clients

SEC Edgar MCP works with any MCP-compatible client. Here's a comprehensive list of available clients and how to configure them.

## Desktop Applications

### Claude Desktop

<Card title="Claude Desktop" icon="robot" href="https://claude.ai/download">
  **Platform:** Windows, macOS, Linux\
  **Type:** Official Anthropic desktop app\
  **Best for:** Individual users, AI-powered research

  Claude Desktop is the most popular MCP client, providing direct integration with Claude AI for interactive financial analysis.

  **Configuration file location:**

  * **macOS/Linux:** `~/.config/claude-desktop/config.json`
  * **Windows:** `%APPDATA%\Claude\claude-desktop\config.json`

  ```json theme={null}
  {
    "mcpServers": {
      "sec-edgar-mcp": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "-e", "SEC_EDGAR_USER_AGENT=Your Name (email@example.com)",
          "stefanoamorelli/sec-edgar-mcp:latest"
        ]
      }
    }
  }
  ```
</Card>

### Continue

<Card title="Continue" icon="code" href="https://continue.dev">
  **Platform:** VS Code, JetBrains IDEs\
  **Type:** IDE extension\
  **Best for:** Developers, code-integrated analysis

  Continue brings AI assistance directly to your IDE with MCP support for contextual coding help.

  **Configuration:** Add to `.continue/config.json`:

  ```json theme={null}
  {
    "models": [...],
    "mcpServers": {
      "sec-edgar-mcp": {
        "command": "uvx",
        "args": [
          "--from", "git+https://github.com/stefanoamorelli/sec-edgar-mcp.git",
          "sec-edgar-mcp"
        ],
        "env": {
          "SEC_EDGAR_USER_AGENT": "Your Name (email@example.com)"
        }
      }
    }
  }
  ```
</Card>

### Cline (formerly Claude Dev)

<Card title="Cline" icon="terminal" href="https://github.com/cline/cline">
  **Platform:** VS Code\
  **Type:** VS Code extension\
  **Best for:** Autonomous coding tasks, file management

  Cline is an autonomous AI assistant that can create, edit, and execute code with human oversight.

  **Configuration:** Through VS Code settings or `settings.json`:

  ```json theme={null}
  {
    "cline.mcpServers": {
      "sec-edgar-mcp": {
        "command": "python",
        "args": ["-m", "sec_edgar_mcp.server"],
        "env": {
          "SEC_EDGAR_USER_AGENT": "Your Name (email@example.com)"
        }
      }
    }
  }
  ```
</Card>

## Command Line Tools

### MCP CLI

<Card title="MCP CLI" icon="terminal" href="https://github.com/modelcontextprotocol/mcp-cli">
  **Platform:** All platforms\
  **Type:** Command-line interface\
  **Best for:** Testing, debugging, automation

  Official command-line tool for testing and debugging MCP servers.

  ```bash theme={null}
  # Install MCP CLI
  npm install -g @modelcontextprotocol/cli

  # Connect to SEC Edgar MCP
  mcp connect "docker run -i --rm -e SEC_EDGAR_USER_AGENT='Test User (test@example.com)' stefanoamorelli/sec-edgar-mcp:latest"

  # List available tools
  mcp tools list

  # Call a tool
  mcp call lookup_company_cik '{"company_name": "Apple"}'
  ```
</Card>

### MCP Client SDK

<Card title="MCP Client SDK" icon="code" href="https://modelcontextprotocol.io/docs/concepts/clients">
  **Platform:** Python, TypeScript/JavaScript\
  **Type:** SDK for building custom clients\
  **Best for:** Custom integrations, automation

  Build your own MCP client using official SDKs.

  **Python example:**

  ```python theme={null}
  from mcp import Client
  import asyncio

  async def main():
      async with Client() as client:
          # Connect to SEC Edgar MCP
          await client.connect(
              command="python",
              args=["-m", "sec_edgar_mcp.server"],
              env={"SEC_EDGAR_USER_AGENT": "Bot (bot@example.com)"}
          )
          
          # List available tools
          tools = await client.list_tools()
          
          # Call a tool
          result = await client.call_tool(
              "lookup_company_cik",
              {"company_name": "Tesla"}
          )
          print(result)

  asyncio.run(main())
  ```
</Card>

## Web Applications

### LibreChat

<Card title="LibreChat" icon="message" href="https://github.com/danny-avila/LibreChat">
  **Platform:** Web (self-hosted)\
  **Type:** Multi-model chat interface\
  **Best for:** Teams, self-hosted deployments

  Open-source AI chat platform with MCP support for multiple models.

  **Configuration:** Add to `librechat.yaml`:

  ```yaml theme={null}
  mcp:
    servers:
      sec-edgar:
        command: docker
        args:
          - run
          - -i
          - --rm
          - -e
          - "SEC_EDGAR_USER_AGENT=LibreChat (admin@example.com)"
          - stefanoamorelli/sec-edgar-mcp:latest
  ```
</Card>

### Open WebUI

<Card title="Open WebUI" icon="browser" href="https://github.com/open-webui/open-webui">
  **Platform:** Web (self-hosted)\
  **Type:** Web interface for LLMs\
  **Best for:** Self-hosted AI assistants

  Feature-rich web UI for various LLMs with extensibility through tools and functions.

  **Note:** MCP support is in development. Check their documentation for updates.
</Card>

## Mobile & Emerging Clients

### Mobile MCP Clients

<Note>
  Mobile MCP clients are emerging. Check the [MCP ecosystem](https://modelcontextprotocol.io/ecosystem) for the latest mobile client developments.
</Note>

### Custom Integrations

<Tip>
  Any application can become an MCP client by implementing the [MCP protocol specification](https://modelcontextprotocol.io/specification). The protocol uses JSON-RPC 2.0 over stdio, SSE, or WebSocket transports.
</Tip>

## Configuration Best Practices

<AccordionGroup>
  <Accordion title="Environment Variables">
    Always set the `SEC_EDGAR_USER_AGENT` with your actual name and email:

    ```bash theme={null}
    SEC_EDGAR_USER_AGENT="John Doe (john.doe@company.com)"
    ```

    The SEC requires proper identification for API access.
  </Accordion>

  <Accordion title="Docker vs Direct Installation">
    **Docker (Recommended):**

    * Isolated environment
    * No Python version conflicts
    * Consistent across platforms

    **Direct Installation (pip/uvx):**

    * Lower resource usage
    * Faster startup time
    * Easier debugging
  </Accordion>

  <Accordion title="Connection Testing">
    After configuration, test your connection:

    1. Restart your MCP client
    2. Check if SEC Edgar tools are discovered
    3. Try a simple query like company lookup
    4. Verify tool responses include SEC URLs
  </Accordion>

  <Accordion title="Troubleshooting">
    Common issues and solutions:

    * **Tools not appearing:** Check JSON syntax and restart client
    * **Connection errors:** Verify Docker is running or Python path is correct
    * **SEC errors:** Ensure User-Agent includes valid email
    * **Rate limiting:** Add delays between requests
  </Accordion>
</AccordionGroup>

## Finding More Clients

The MCP ecosystem is rapidly growing. Find the latest clients and tools:

* [MCP Ecosystem Directory](https://modelcontextprotocol.io/ecosystem)
* [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers)
* [MCP GitHub Topics](https://github.com/topics/mcp)
* [MCP Discord Community](https://discord.gg/modelcontextprotocol)

## Next Steps

<CardGroup>
  <Card title="Configuration Guide" icon="gear" href="/setup/configuration">
    Advanced configuration options
  </Card>

  <Card title="Docker Setup" icon="docker" href="/setup/docker">
    Detailed Docker installation guide
  </Card>

  <Card title="Troubleshooting" icon="bug" href="/setup/troubleshooting">
    Common issues and solutions
  </Card>

  <Card title="Tools Overview" icon="wrench" href="/tools/overview">
    Explore available SEC Edgar tools
  </Card>
</CardGroup>


# Troubleshooting
Source: https://sec-edgar-mcp.amorelli.tech/setup/troubleshooting

Common issues and solutions

## Common Issues

### Server Not Starting

1. Check Python version (3.11+ required)
2. Verify environment variables are set
3. Ensure Docker is running (if using Docker)

### Tools Not Discovered

1. Restart your MCP client
2. Check JSON configuration syntax
3. Verify server starts without errors

### SEC API Errors

1. Check User-Agent header format
2. Verify internet connectivity
3. Respect rate limiting (10 requests/second max)


# Lookup Company CIK
Source: https://sec-edgar-mcp.amorelli.tech/tools/company/lookup-cik

Convert ticker symbols to CIK numbers

## Overview

The `lookup_company_cik` tool converts company ticker symbols to CIK (Central Index Key) numbers for more reliable API performance.

## Parameters

* `ticker` (string): Company ticker symbol (e.g., "AAPL")

## Example Usage

```text theme={null}
"What is Apple's CIK number?"
```

## Response Format

```json theme={null}
{
  "success": true,
  "cik": "0000320193",
  "ticker": "AAPL",
  "suggestion": "Use CIK '0000320193' instead of ticker 'AAPL' for more reliable and faster API calls"
}
```


# Tools Overview
Source: https://sec-edgar-mcp.amorelli.tech/tools/overview

Complete reference for all SEC Edgar MCP tools

## Tool Categories

SEC Edgar MCP provides comprehensive tools organized into four main categories, each designed to access different aspects of SEC EDGAR data with exact precision and verifiable references.

<CardGroup>
  <Card title="Company Tools" icon="building" href="/tools/company/lookup-cik">
    Look up companies, get basic information, and access company facts
  </Card>

  <Card title="Filing Tools" icon="file-text" href="/tools/filings/recent-filings">
    Access recent filings, analyze content, and extract specific sections
  </Card>

  <Card title="Financial Tools" icon="chart-bar" href="/tools/financial/financial-statements">
    Extract financial statements with direct XBRL parsing for exact precision
  </Card>

  <Card title="Insider Trading Tools" icon="user-tie" href="/tools/insider/form-345">
    Monitor insider transactions and analyze Form 3, 4, and 5 filings
  </Card>
</CardGroup>

## Core Principles

All SEC Edgar MCP tools follow these core principles:

### Exact Precision

* **No Rounding**: Financial data maintains exact numeric precision as filed with the SEC
* **Direct XBRL Parsing**: Uses regex patterns to extract data directly from SEC filings
* **Deterministic Processing**: Consistent, repeatable results based solely on filing data

### Verifiable References

* **SEC URLs**: Every response includes clickable links to original SEC filings
* **Filing Metadata**: Complete accession numbers, filing dates, and form types
* **Source Attribution**: Clear indication of data source and extraction method

### AI Safety Features

* **Deterministic Responses**: Strict instructions prevent AI hallucination
* **Filing-Only Data**: Responses based exclusively on actual SEC filing content
* **Verification Links**: Users can independently verify all data at provided SEC URLs

## Available Tools

### Company Tools

<AccordionGroup>
  <Accordion title="lookup_company_cik">
    **Purpose**: Convert company ticker symbols to CIK numbers for more reliable API calls

    **Parameters**:

    * `ticker` (string): Company ticker symbol (e.g., "AAPL")

    **Returns**: CIK number and suggestion to use CIK for better performance

    **Example Use**: Find Apple's CIK number to use in other tools
  </Accordion>

  <Accordion title="get_company_info">
    **Purpose**: Get detailed company information including basic facts and identifiers

    **Parameters**:

    * `identifier` (string): Company CIK, ticker, or name

    **Returns**: Company details, SIC code, exchange, state, fiscal year end

    **Example Use**: Get comprehensive company profile information
  </Accordion>

  <Accordion title="get_company_facts">
    **Purpose**: Extract key financial metrics from company facts database

    **Parameters**:

    * `identifier` (string): Company CIK, ticker, or name

    **Returns**: Latest financial metrics with exact values and filing references

    **Example Use**: Get current financial snapshot of a company
  </Accordion>
</AccordionGroup>

### Filing Tools

<AccordionGroup>
  <Accordion title="get_recent_filings">
    **Purpose**: Get recent SEC filings for a company or across all companies

    **Parameters**:

    * `identifier` (string, optional): Company CIK, ticker, or name
    * `form_type` (string/array, optional): Specific form types (e.g., "10-K", \["10-K", "10-Q"])
    * `days` (number): Number of days to look back (default: 30)
    * `limit` (number): Maximum number of results (default: 40)

    **Returns**: List of filings with metadata and direct SEC links

    **Example Use**: Monitor recent 8-K filings for material events
  </Accordion>

  <Accordion title="get_filing_content">
    **Purpose**: Get the complete content of a specific SEC filing

    **Parameters**:

    * `identifier` (string): Company CIK, ticker, or name
    * `accession_number` (string): SEC accession number

    **Returns**: Full filing text content with structured data extraction

    **Example Use**: Read the complete text of a 10-K filing
  </Accordion>

  <Accordion title="analyze_8k_filing">
    **Purpose**: Analyze 8-K filings for specific material events and press releases

    **Parameters**:

    * `identifier` (string): Company CIK, ticker, or name
    * `accession_number` (string): 8-K filing accession number

    **Returns**: Detailed analysis of 8-K items, events, and press releases

    **Example Use**: Analyze what triggered a specific 8-K filing
  </Accordion>

  <Accordion title="get_filing_sections">
    **Purpose**: Extract specific sections from 10-K or 10-Q filings

    **Parameters**:

    * `identifier` (string): Company CIK, ticker, or name
    * `accession_number` (string): Filing accession number
    * `form_type` (string): "10-K" or "10-Q"

    **Returns**: Business section, risk factors, MD\&A, and other key sections

    **Example Use**: Get just the risk factors section from a 10-K
  </Accordion>
</AccordionGroup>

### Financial Tools

<AccordionGroup>
  <Accordion title="get_financial_statements">
    **Purpose**: Extract complete financial statements with direct XBRL parsing

    **Parameters**:

    * `identifier` (string): Company CIK, ticker, or name
    * `statement_type` (string): "income", "balance", "cash", or "all"

    **Returns**: Financial statements with exact precision and filing references

    **Example Use**: Get Tesla's latest income statement with exact numbers
  </Accordion>

  <Accordion title="get_xbrl_concepts">
    **Purpose**: Extract specific XBRL concepts with exact values from filings

    **Parameters**:

    * `identifier` (string): Company CIK, ticker, or name
    * `concepts` (array, optional): Specific XBRL concepts to extract
    * `accession_number` (string, optional): Specific filing
    * `form_type` (string): Filing form type (default: "10-K")

    **Returns**: Exact XBRL concept values with context and period information

    **Example Use**: Get exact revenue figure from latest 10-K
  </Accordion>

  <Accordion title="discover_company_metrics">
    **Purpose**: Discover all available financial metrics for a company

    **Parameters**:

    * `identifier` (string): Company CIK, ticker, or name
    * `search_term` (string, optional): Filter metrics by search term

    **Returns**: List of available metrics with counts and latest periods

    **Example Use**: See what financial metrics are available for analysis
  </Accordion>
</AccordionGroup>

### Insider Trading Tools

<AccordionGroup>
  <Accordion title="get_insider_transactions">
    **Purpose**: Get insider trading transactions from Form 3, 4, and 5 filings

    **Parameters**:

    * `identifier` (string): Company CIK, ticker, or name
    * `days` (number): Number of days to look back (default: 90)
    * `transaction_type` (string, optional): Filter by transaction type

    **Returns**: Detailed insider transactions with exact values and dates

    **Example Use**: Monitor recent insider buying/selling activity
  </Accordion>

  <Accordion title="analyze_form_345">
    **Purpose**: Detailed analysis of specific Form 3, 4, or 5 insider filings

    **Parameters**:

    * `identifier` (string): Company CIK, ticker, or name
    * `accession_number` (string): Form 3/4/5 accession number

    **Returns**: Complete insider transaction analysis with all details

    **Example Use**: Analyze a specific insider's large transaction
  </Accordion>
</AccordionGroup>

## Tool Usage Patterns

### Basic Company Research

1. **Start with company lookup**: Use `lookup_company_cik` to get reliable CIK
2. **Get company profile**: Use `get_company_info` for basic information
3. **Check recent activity**: Use `get_recent_filings` to see latest filings

### Financial Analysis

1. **Get financial statements**: Use `get_financial_statements` for complete data
2. **Extract specific metrics**: Use `get_xbrl_concepts` for precise values
3. **Compare periods**: Use multiple calls to analyze trends

### Due Diligence

1. **Company background**: Start with `get_company_info`
2. **Recent filings review**: Use `get_recent_filings` and `analyze_8k_filing`
3. **Financial health**: Use `get_financial_statements`
4. **Insider activity**: Use `get_insider_transactions`

### Compliance Monitoring

1. **Monitor filings**: Regular `get_recent_filings` calls
2. **Analyze events**: Use `analyze_8k_filing` for material events
3. **Track insider trading**: Use `get_insider_transactions`

## Data Quality Guarantees

<Note>
  **Exact Precision Promise**: All financial data is extracted directly from SEC XBRL filings with exact numeric precision. No estimates, calculations, or rounding are applied.
</Note>

### Verification Process

1. **Independent Verification**: All responses include SEC URLs for independent verification
2. **Filing References**: Complete accession numbers and filing dates provided
3. **Source Attribution**: Clear indication of data extraction method and source

### Error Handling

* **Graceful Failures**: Tools return structured error messages when data is unavailable
* **Fallback Methods**: Multiple extraction methods ensure maximum data availability
* **Clear Error Messages**: Specific error descriptions help diagnose issues

## Rate Limiting and Best Practices

### SEC API Guidelines

* **10 requests per second maximum** (automatically enforced)
* **Required User-Agent header** with name and email
* **Respectful usage** of SEC resources

### Performance Tips

* **Use CIK numbers** instead of tickers for better performance
* **Cache results** when possible to reduce API calls
* **Batch requests** when analyzing multiple companies

### Error Recovery

* **Retry logic**: Built-in retry for transient failures
* **Alternative methods**: Multiple extraction approaches for reliability
* **Clear diagnostics**: Detailed error messages for troubleshooting

## Next Steps

<CardGroup>
  <Card title="Company Tools" icon="building" href="/tools/company/lookup-cik">
    Start with company lookup and information tools
  </Card>

  <Card title="Financial Analysis" icon="chart-bar" href="/tools/financial/financial-statements">
    Extract precise financial data from SEC filings
  </Card>

  <Card title="Use Cases" icon="lightbulb" href="/use-cases/financial-analysis">
    See real-world examples and applications
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Technical API documentation and schemas
  </Card>
</CardGroup>


# Financial Analysis
Source: https://sec-edgar-mcp.amorelli.tech/use-cases/financial-analysis

Using SEC Edgar MCP for comprehensive financial analysis and research

## Overview

SEC Edgar MCP provides powerful tools for financial analysis by giving AI assistants direct access to official SEC EDGAR filings with exact precision. This enables comprehensive analysis of company financial performance, trend analysis, and peer comparisons using authoritative data sources.

<Tip>
  All financial data is extracted directly from SEC XBRL filings with exact numeric precision - no rounding or approximation is applied.
</Tip>

## Common Analysis Workflows

### 1. Company Financial Health Assessment

<Steps>
  <Step title="Get Company Information">
    Start with basic company identification and facts:

    ```text theme={null}
    "Get me basic information about Apple Inc including their CIK number"
    ```

    **Tools Used**: `get_company_info`, `lookup_company_cik`
  </Step>

  <Step title="Extract Latest Financial Statements">
    Get complete financial statements from the most recent 10-K or 10-Q:

    ```text theme={null}
    "Show me Apple's latest financial statements including income statement, balance sheet, and cash flow"
    ```

    **Tools Used**: `get_financial_statements`
  </Step>

  <Step title="Analyze Key Metrics">
    Extract specific financial metrics with exact precision:

    ```text theme={null}
    "Get Apple's exact revenue, net income, total assets, and cash position from their latest filing"
    ```

    **Tools Used**: `get_xbrl_concepts`, `get_company_facts`
  </Step>
</Steps>

### 2. Trend Analysis Over Time

<Steps>
  <Step title="Identify Historical Filings">
    Find relevant filings across multiple periods:

    ```text theme={null}
    "Show me Apple's 10-K filings from the last 3 years"
    ```

    **Tools Used**: `get_recent_filings`
  </Step>

  <Step title="Extract Consistent Metrics">
    Get the same financial concepts from each period:

    ```text theme={null}
    "Extract revenue, gross profit, and net income from Apple's 2021, 2022, and 2023 10-K filings"
    ```

    **Tools Used**: `get_xbrl_concepts` (multiple calls with different accession numbers)
  </Step>

  <Step title="Calculate Growth Rates">
    AI can calculate growth rates using the exact data:

    ```text theme={null}
    "Calculate Apple's revenue growth rate over the last 3 years using the exact SEC filing data"
    ```
  </Step>
</Steps>

### 3. Peer Comparison Analysis

<Steps>
  <Step title="Identify Comparable Companies">
    Start with companies in the same sector:

    ```text theme={null}
    "Get financial statements for Apple, Microsoft, and Google for peer comparison"
    ```
  </Step>

  <Step title="Extract Standardized Metrics">
    Use consistent XBRL concepts across companies:

    ```text theme={null}
    "Compare revenue, operating income, and total assets for Apple vs Microsoft vs Google using their latest 10-K filings"
    ```
  </Step>

  <Step title="Analyze Ratios and Margins">
    Calculate financial ratios using exact data:

    ```text theme={null}
    "Calculate and compare gross margins, operating margins, and ROA for these three companies"
    ```
  </Step>
</Steps>

## Advanced Analysis Techniques

### Cash Flow Analysis

<AccordionGroup>
  <Accordion title="Operating Cash Flow Quality">
    **Objective**: Assess the quality and sustainability of operating cash flows

    **Analysis Steps**:

    1. Extract operating cash flow from cash flow statement
    2. Compare to net income (cash vs. earnings quality)
    3. Analyze working capital changes
    4. Look for unusual items or adjustments

    **Example Query**:

    ```text theme={null}
    "Get Apple's operating cash flow, net income, and working capital changes from their latest 10-K. Analyze the quality of their earnings."
    ```
  </Accordion>

  <Accordion title="Free Cash Flow Analysis">
    **Objective**: Calculate and analyze free cash flow generation

    **Analysis Steps**:

    1. Get operating cash flow from cash flow statement
    2. Extract capital expenditures (CapEx)
    3. Calculate free cash flow (OCF - CapEx)
    4. Analyze free cash flow yield and trends

    **Example Query**:

    ```text theme={null}
    "Calculate Tesla's free cash flow by getting their operating cash flow and capital expenditures from the latest 10-K"
    ```
  </Accordion>

  <Accordion title="Capital Allocation Analysis">
    **Objective**: Understand how companies allocate capital

    **Analysis Steps**:

    1. Extract cash flows from investing activities
    2. Analyze financing activities (dividends, share buybacks, debt)
    3. Look for acquisition and investment spending
    4. Assess capital efficiency

    **Example Query**:

    ```text theme={null}
    "Analyze Microsoft's capital allocation by showing their investing and financing cash flows, including acquisitions, dividends, and share repurchases"
    ```
  </Accordion>
</AccordionGroup>

### Balance Sheet Analysis

<AccordionGroup>
  <Accordion title="Liquidity Analysis">
    **Key Metrics**: Current ratio, quick ratio, cash position

    **XBRL Concepts**:

    * `AssetsCurrent` (Current Assets)
    * `LiabilitiesCurrent` (Current Liabilities)
    * `CashAndCashEquivalentsAtCarryingValue`
    * `AccountsReceivableNetCurrent`
    * `InventoryNet`

    **Example Analysis**:

    ```text theme={null}
    "Analyze Amazon's liquidity by calculating their current ratio and quick ratio using exact balance sheet data"
    ```
  </Accordion>

  <Accordion title="Debt Analysis">
    **Key Metrics**: Debt-to-equity, interest coverage, debt maturity

    **XBRL Concepts**:

    * `LongTermDebtNoncurrent`
    * `DebtCurrent`
    * `StockholdersEquity`
    * `InterestExpense`

    **Example Analysis**:

    ```text theme={null}
    "Evaluate Tesla's debt position including total debt, debt-to-equity ratio, and interest expense burden"
    ```
  </Accordion>

  <Accordion title="Asset Quality Analysis">
    **Focus Areas**: Asset composition, intangibles, impairments

    **XBRL Concepts**:

    * `PropertyPlantAndEquipmentNet`
    * `Goodwill`
    * `IntangibleAssetsNetExcludingGoodwill`
    * `AccountsReceivableNetCurrent`

    **Example Analysis**:

    ```text theme={null}
    "Analyze the composition of Microsoft's assets, focusing on tangible vs intangible assets and goodwill"
    ```
  </Accordion>
</AccordionGroup>

### Income Statement Analysis

<AccordionGroup>
  <Accordion title="Revenue Quality Analysis">
    **Objective**: Assess revenue recognition and sustainability

    **Key Areas**:

    * Revenue growth rates and trends
    * Revenue mix and segment analysis
    * Deferred revenue and contracts
    * One-time vs. recurring revenue

    **Example Query**:

    ```text theme={null}
    "Analyze Salesforce's revenue quality by looking at their subscription revenue vs. professional services, plus deferred revenue trends"
    ```
  </Accordion>

  <Accordion title="Profitability Analysis">
    **Key Metrics**: Gross margin, operating margin, net margin

    **XBRL Concepts**:

    * `Revenues`
    * `CostOfRevenue`
    * `GrossProfit`
    * `OperatingIncomeLoss`
    * `NetIncomeLoss`

    **Example Analysis**:

    ```text theme={null}
    "Calculate and analyze Apple's gross margin, operating margin, and net margin trends over the last 3 years"
    ```
  </Accordion>

  <Accordion title="Expense Analysis">
    **Focus Areas**: Operating leverage, cost structure, efficiency

    **XBRL Concepts**:

    * `ResearchAndDevelopmentExpense`
    * `SellingGeneralAndAdministrativeExpense`
    * `DepreciationDepletionAndAmortization`

    **Example Analysis**:

    ```text theme={null}
    "Analyze Google's R&D spending as a percentage of revenue and compare their operating leverage over time"
    ```
  </Accordion>
</AccordionGroup>

## Industry-Specific Analysis

### Technology Companies

<CardGroup>
  <Card title="SaaS Metrics" icon="cloud">
    **Key Focus**:

    * Subscription revenue growth
    * Deferred revenue (future bookings)
    * Customer acquisition costs
    * R\&D investment levels

    **Example**: Analyzing Salesforce or ServiceNow
  </Card>

  <Card title="Hardware Companies" icon="microchip">
    **Key Focus**:

    * Inventory management
    * Gross margin trends
    * CapEx for manufacturing
    * Supply chain efficiency

    **Example**: Analyzing Apple or Intel
  </Card>
</CardGroup>

### Financial Services

<CardGroup>
  <Card title="Banks" icon="building-columns">
    **Key Focus**:

    * Net interest margin
    * Loan loss provisions
    * Tier 1 capital ratios
    * Return on assets/equity

    **Example**: Analyzing JPMorgan or Bank of America
  </Card>

  <Card title="Insurance" icon="shield">
    **Key Focus**:

    * Underwriting ratios
    * Investment income
    * Reserve adequacy
    * Combined ratios

    **Example**: Analyzing Berkshire Hathaway or Progressive
  </Card>
</CardGroup>

### Retail and Consumer

<CardGroup>
  <Card title="Retail" icon="store">
    **Key Focus**:

    * Same-store sales growth
    * Inventory turnover
    * Operating leverage
    * Store productivity

    **Example**: Analyzing Walmart or Target
  </Card>

  <Card title="Consumer Brands" icon="shopping-bag">
    **Key Focus**:

    * Brand investment (marketing)
    * Gross margin trends
    * Market share dynamics
    * Distribution efficiency

    **Example**: Analyzing Coca-Cola or P\&G
  </Card>
</CardGroup>

## Red Flags and Risk Analysis

### Financial Statement Red Flags

<Warning>
  Use SEC Edgar MCP to identify potential warning signs in financial statements:
</Warning>

<AccordionGroup>
  <Accordion title="Revenue Quality Issues">
    **Warning Signs to Look For**:

    * Declining cash conversion (revenue growing faster than cash flow)
    * Increasing accounts receivable relative to sales
    * Growing deferred revenue without corresponding cash
    * Unusual revenue timing or recognition

    **Analysis Query**:

    ```text theme={null}
    "Compare Company X's revenue growth to their operating cash flow growth and analyze their accounts receivable trends"
    ```
  </Accordion>

  <Accordion title="Expense and Asset Quality">
    **Warning Signs to Look For**:

    * Unusual asset impairments
    * Growing other assets without explanation
    * Declining asset turnover ratios
    * Inconsistent expense categorization

    **Analysis Query**:

    ```text theme={null}
    "Analyze Company Y's asset base for any unusual growth in intangibles or other assets, and check for recent impairment charges"
    ```
  </Accordion>

  <Accordion title="Cash Flow Concerns">
    **Warning Signs to Look For**:

    * Operating cash flow significantly below net income
    * Increasing working capital requirements
    * Heavy reliance on financing activities for cash
    * Declining free cash flow despite earnings growth

    **Analysis Query**:

    ```text theme={null}
    "Compare Company Z's net income to operating cash flow over the last 3 years and analyze working capital changes"
    ```
  </Accordion>
</AccordionGroup>

## Event-Driven Analysis

### Material Event Analysis

Use 8-K filings to analyze material events:

<Steps>
  <Step title="Monitor Recent 8-K Filings">
    ```text theme={null}
    "Show me all 8-K filings for Apple in the last 30 days"
    ```
  </Step>

  <Step title="Analyze Specific Events">
    ```text theme={null}
    "Analyze Apple's latest 8-K filing for material events and press releases"
    ```
  </Step>

  <Step title="Assess Financial Impact">
    ```text theme={null}
    "Based on the 8-K analysis, what are the potential financial implications of these events?"
    ```
  </Step>
</Steps>

### Earnings Analysis

<CardGroup>
  <Card title="Pre-Earnings Research" icon="magnifying-glass">
    **Before earnings release**:

    * Review latest 10-Q for trends
    * Analyze recent 8-K filings for updates
    * Check insider trading activity
    * Review segment performance
  </Card>

  <Card title="Post-Earnings Analysis" icon="chart-line">
    **After earnings release**:

    * Compare actual vs. historical trends
    * Analyze cash flow quality
    * Review forward guidance (8-K)
    * Assess margin expansion/compression
  </Card>
</CardGroup>

## Best Practices

### Data Verification

<Tip>
  Always use the SEC URLs provided in SEC Edgar MCP responses to verify data independently. This ensures accuracy and builds confidence in your analysis.
</Tip>

1. **Check Filing Dates**: Ensure you're comparing data from similar periods
2. **Verify Calculations**: Use exact figures from XBRL extractions
3. **Read Footnotes**: Access full filing content for important disclosures
4. **Cross-Reference**: Compare multiple tools' outputs for consistency

### Analysis Documentation

1. **Source Attribution**: Always note which SEC filing and tool provided each data point
2. **Methodology**: Document your analysis approach and assumptions
3. **Time Consistency**: Use consistent time periods for trend analysis
4. **Peer Selection**: Document why specific peers were chosen for comparison

### Continuous Monitoring

<CardGroup>
  <Card title="Regular Updates" icon="refresh">
    Monitor quarterly filings (10-Q) and annual reports (10-K) for updated financial data
  </Card>

  <Card title="Event Monitoring" icon="bell">
    Watch for 8-K filings that might indicate material changes affecting your analysis
  </Card>
</CardGroup>

## Advanced Use Cases

### Acquisition Analysis

When evaluating M\&A targets or understanding strategic moves:

```text theme={null}
"Analyze Company A's acquisition of Company B by looking at recent 8-K filings, pro forma impacts, and balance sheet changes"
```

### Turnaround Situations

For companies in financial distress:

```text theme={null}
"Analyze Company X's liquidity position, debt maturities, and cash burn rate using their latest 10-Q and recent 8-K filings"
```

### ESG Integration

Environmental, Social, and Governance analysis:

```text theme={null}
"Review Company Y's latest 10-K for sustainability investments, regulatory compliance costs, and governance-related expenses"
```

## Next Steps

<CardGroup>
  <Card title="Investment Research" icon="chart-line" href="/use-cases/investment-research">
    Learn how to use SEC Edgar MCP for investment decision-making
  </Card>

  <Card title="Financial Tools" icon="calculator" href="/tools/financial/financial-statements">
    Explore detailed financial analysis tools
  </Card>
</CardGroup>