Skip to main content

​
System Requirements

Python

Version: 3.11 or higher
Required: Yes

Docker

Version: Any recent version
Required: Optional but recommended

MCP Client

Examples: Claude Desktop, MCP CLI
Required: Yes

​
Installation Methods

Docker provides the most reliable and consistent installation experience:
1

Install Docker

If you don’t have Docker installed:
  • Windows/Mac
  • Linux
Download and install Docker Desktop
2

Pull SEC Edgar MCP Image

docker pull stefanoamorelli/sec-edgar-mcp:latest
The Docker image is automatically built and tested, ensuring consistency across all platforms.
3

Verify Installation

Test the Docker image:
docker run --rm stefanoamorelli/sec-edgar-mcp:latest --version

​
Method 2: Python Package (PyPI)

Install directly from Python Package Index:
1

Verify Python Version

python --version
# Should be 3.11 or higher
2

Create Virtual Environment (Recommended)

python -m venv sec-edgar-env
source sec-edgar-env/bin/activate  # On Windows: sec-edgar-env\Scripts\activate
3

Install Package

pip install sec-edgar-mcp
For development dependencies:
pip install sec-edgar-mcp[dev]
4

Verify Installation

python -m sec_edgar_mcp.server --version

​
Method 3: uvx (No Installation Required)

Run directly without installation using uvx:
1

Install uvx

If you don’t have uvx installed:
pip install uvx
# or
pipx install uvx
2

Run SEC Edgar MCP

No installation needed - uvx will handle everything:
uvx --from git+https://github.com/stefanoamorelli/sec-edgar-mcp.git sec-edgar-mcp
uvx automatically manages package installation and updates, making it ideal for quick setup without managing Python environments.
3

Configure MCP Client

Add to your MCP client configuration:
{
  "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)"
      }
    }
  }
}

​
Method 4: Development Installation

For contributors and developers:
1

Clone Repository

git clone https://github.com/stefanoamorelli/sec-edgar-mcp.git
cd sec-edgar-mcp
2

Create Virtual Environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
3

Install in Development Mode

pip install -e .[dev]
4

Run Tests

python -m pytest tests/

​
Configuration

​
Environment Variables

​
SEC_EDGAR_USER_AGENT
string
required
Required. Must include your name and email address.Example: "John Doe (john@example.com)"
The SEC requires this header and may block requests without proper identification.
​
SEC_EDGAR_CACHE_DIR
string
default:"~/.cache/sec-edgar"
Directory for caching SEC data to improve performance.
​
SEC_EDGAR_RATE_LIMIT
integer
default:"10"
Requests per second limit to respect SEC API guidelines.

​
Setting Environment Variables

  • Linux/Mac
  • Windows
  • Docker
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.

​
MCP Client Configuration

​
Claude Desktop

Add to ~/.config/claude-desktop/config.json:
  • Docker
  • Python
{
  "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": {}
    }
  }
}

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

Company Tools

  • lookup_company_cik
  • get_company_info
  • get_company_facts

Filing Tools

  • get_recent_filings
  • get_filing_content
  • analyze_8k_filing

Financial Tools

  • get_financial_statements
  • extract_financial_data

Insider Tools

  • get_insider_transactions
  • analyze_form_345

​
Troubleshooting

SEC Edgar MCP requires Python 3.11+. Check your version:
python --version
If you have multiple Python versions, you may need to use python3.11 or similar.
On Linux, you may need to add your user to the docker group:
sudo usermod -aG docker $USER
# Logout and login again
Try updating pip and setuptools:
pip install --upgrade pip setuptools wheel
pip install sec-edgar-mcp
  • Verify the JSON configuration syntax
  • Check the MCP client logs
  • Ensure the server starts without errors
  • Restart the MCP client after configuration changes

​
Next Steps

Quickstart Guide

Get up and running with your first queries

Configuration

Advanced configuration and customization
⌘I