Skip to main content

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

​
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

​
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

Problem: SEC API returns 403 ForbiddenSolution: Ensure User-Agent includes valid email address:
export SEC_EDGAR_USER_AGENT="John Doe (john.doe@company.com)"
Problem: Too many requests errorsSolution: Reduce rate limit:
export SEC_EDGAR_RATE_LIMIT="5"
Problem: Cannot write to cache directorySolution: Fix permissions:
mkdir -p ~/.cache/sec-edgar
chmod 755 ~/.cache/sec-edgar
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"