Installation

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

Method 1: Docker (Recommended)

Docker provides the most reliable and consistent installation experience:

Install Docker

If you don’t have Docker installed:

Windows/Mac
Linux

Download and install Docker Desktop

# 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

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.

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:

Verify Python Version

python --version
# Should be 3.11 or higher

Create Virtual Environment (Recommended)

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

Install Package

pip install sec-edgar-mcp

For development dependencies:

pip install sec-edgar-mcp[dev]

Verify Installation

python -m sec_edgar_mcp.server --version

Method 3: uvx (No Installation Required)

Run directly without installation using uvx:

Install uvx

If you don’t have uvx installed:

pip install uvx
# or
pipx install uvx

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.

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:

Clone Repository

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

Create Virtual Environment

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

Install in Development Mode

pip install -e .[dev]

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.

set SEC_EDGAR_USER_AGENT="Your Name (name@domain.com)"
set SEC_EDGAR_CACHE_DIR="C:\sec-edgar-cache"

Or use PowerShell:

$env:SEC_EDGAR_USER_AGENT = "Your Name (name@domain.com)"

Pass environment variables to Docker:

docker run -e SEC_EDGAR_USER_AGENT="Your Name (name@domain.com)" \\
           -e SEC_EDGAR_CACHE_DIR="/cache" \\
           stefanoamorelli/sec-edgar-mcp:latest

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

{
  "mcpServers": {
    "sec-edgar-mcp": {
      "command": "python",
      "args": ["-m", "sec_edgar_mcp.server"],
      "env": {
        "SEC_EDGAR_USER_AGENT": "Your Name (name@domain.com)"
      }
    }
  }
}

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:

Restart your MCP client
Check for tool discovery - You should see SEC Edgar tools available
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

Python Version Issues

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.

Docker Permission Issues

On Linux, you may need to add your user to the docker group:

sudo usermod -aG docker $USER
# Logout and login again

Package Installation Failures

Try updating pip and setuptools:

pip install --upgrade pip setuptools wheel
pip install sec-edgar-mcp

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

Next Steps

Quickstart Guide

Get up and running with your first queries

Configuration

Advanced configuration and customization

Getting Started

Setup

Core Concepts

Tools Reference

Use Cases

About

System Requirements

Python

Docker

MCP Client

Installation Methods

Method 1: Docker (Recommended)

Method 2: Python Package (PyPI)

Method 3: uvx (No Installation Required)

Method 4: Development Installation

Configuration

Environment Variables

Setting Environment Variables

MCP Client Configuration

Claude Desktop

Other MCP Clients

Verification

Test Connection

Expected Tools

Company Tools

Filing Tools

Financial Tools

Insider Tools

Troubleshooting

Next Steps

Quickstart Guide

Configuration

​System Requirements

Python

Docker

MCP Client

​Installation Methods

​Method 1: Docker (Recommended)

​Method 2: Python Package (PyPI)

​Method 3: uvx (No Installation Required)

​Method 4: Development Installation

​Configuration

​Environment Variables

​Setting Environment Variables

​MCP Client Configuration

​Claude Desktop

​Other MCP Clients

​Verification

​Test Connection

​Expected Tools

Company Tools

Filing Tools

Financial Tools

Insider Tools

​Troubleshooting

​Next Steps

Quickstart Guide

Configuration

System Requirements

Installation Methods

Method 1: Docker (Recommended)

Method 2: Python Package (PyPI)

Method 3: uvx (No Installation Required)

Method 4: Development Installation

Configuration

Environment Variables

Setting Environment Variables

MCP Client Configuration

Claude Desktop

Other MCP Clients

Verification

Test Connection

Expected Tools

Troubleshooting

Next Steps