Configuration

Environment Variables

SEC_EDGAR_USER_AGENT

string

required

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.

export SEC_EDGAR_USER_AGENT="John Doe (john@company.com)"

set SEC_EDGAR_USER_AGENT="John Doe (john@company.com)"

$env:SEC_EDGAR_USER_AGENT = "John Doe (john@company.com)"

SEC_EDGAR_CACHE_DIR

string

default:"~/.cache/sec-edgar"

Directory for caching SEC data to improve performance and reduce API calls.

export SEC_EDGAR_CACHE_DIR="/path/to/custom/cache"

SEC_EDGAR_RATE_LIMIT

integer

default:"10"

Requests per second limit. SEC allows up to 10 requests per second.

export SEC_EDGAR_RATE_LIMIT="8"  # Conservative limit

SEC_EDGAR_TIMEOUT

integer

default:"30"

Request timeout in seconds for SEC API calls.

export SEC_EDGAR_TIMEOUT="60"  # Longer timeout for large filings

SEC_EDGAR_DEBUG

boolean

default:"false"

Enable debug logging for troubleshooting.

export SEC_EDGAR_DEBUG="true"

MCP Client Configuration

Claude Desktop

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

Docker Configuration
Python Configuration

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

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

Other MCP Clients

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

Command

How to start the server:

Docker: docker run ...
Python: python -m sec_edgar_mcp.server

Environment

Required environment variables:

SEC_EDGAR_USER_AGENT
Optional performance tuning vars

Advanced Configuration

Custom Cache Configuration

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

# 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

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

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

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

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:

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:

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:

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

export SEC_EDGAR_MAX_WORKERS="4"  # Concurrent workers
export SEC_EDGAR_BATCH_SIZE="10"  # Batch size for bulk operations

Security Configuration

Network Security

Ensure SEC Edgar MCP only communicates with authorized SEC endpoints.

# 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

Never use fake or misleading User-Agent headers. The SEC requires accurate identification.

# 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

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:

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

Docker
Python

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

python -m sec_edgar_mcp.server --test-config

Connection Testing

Verify SEC API connectivity:

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

Troubleshooting Configuration

User-Agent Rejected

Problem: SEC API returns 403 ForbiddenSolution: Ensure User-Agent includes valid email address:

export SEC_EDGAR_USER_AGENT="John Doe (john.doe@company.com)"

Rate Limiting Errors

Problem: Too many requests errorsSolution: Reduce rate limit:

export SEC_EDGAR_RATE_LIMIT="5"

Cache Permission Issues

Problem: Cannot write to cache directorySolution: Fix permissions:

mkdir -p ~/.cache/sec-edgar
chmod 755 ~/.cache/sec-edgar

Timeout Issues

Problem: Requests timing outSolution: Increase timeout:

export SEC_EDGAR_TIMEOUT="120"

Configuration Examples

Development Setup

# 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

# 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

# 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"

Getting Started

Setup

Core Concepts

Tools Reference

Use Cases

About

Environment Variables

MCP Client Configuration

Claude Desktop

Other MCP Clients

Command

Environment

Advanced Configuration

Custom Cache Configuration

Rate Limiting Strategy

Timeout Configuration

Docker-Specific Configuration

Volume Mounting

Resource Limits

Network Configuration

Performance Tuning

Memory Optimization

Concurrent Processing

Security Configuration

Network Security

User Agent Security

Logging Configuration

Enable Debug Logging

Structured Logging

Validation

Configuration Validation

Connection Testing

Troubleshooting Configuration

Configuration Examples

Development Setup

Production Setup

High-Volume Setup

​Environment Variables

​MCP Client Configuration

​Claude Desktop

​Other MCP Clients

Command

Environment

​Advanced Configuration

​Custom Cache Configuration

​Rate Limiting Strategy

​Timeout Configuration

​Docker-Specific Configuration

​Volume Mounting

​Resource Limits

​Network Configuration

​Performance Tuning

​Memory Optimization

​Concurrent Processing

​Security Configuration

​Network Security

​User Agent Security

​Logging Configuration

​Enable Debug Logging

​Structured Logging

​Validation

​Configuration Validation

​Connection Testing

​Troubleshooting Configuration

​Configuration Examples

​Development Setup

​Production Setup

​High-Volume Setup

Environment Variables

MCP Client Configuration

Claude Desktop

Other MCP Clients

Advanced Configuration

Custom Cache Configuration

Rate Limiting Strategy

Timeout Configuration

Docker-Specific Configuration

Volume Mounting

Resource Limits

Network Configuration

Performance Tuning

Memory Optimization

Concurrent Processing

Security Configuration

Network Security

User Agent Security

Logging Configuration

Enable Debug Logging

Structured Logging

Validation

Configuration Validation

Connection Testing

Troubleshooting Configuration

Configuration Examples

Development Setup

Production Setup

High-Volume Setup