README.md

metadata

title: SEC Financial Report MCP Server
emoji: 📊
colorFrom: blue
colorTo: green
sdk: docker
pinned: true
license: mit
app_port: 7860
short_description: MCP Server for querying SEC EDGAR financial data

SEC Financial Report MCP Server

A FastAPI-based MCP (Model Context Protocol) Server for querying SEC EDGAR financial data.

Features

• Company Search: Search companies by name and get CIK information
• Company Information: Retrieve detailed company information from SEC EDGAR
• Filings Retrieval: Get all historical filings (10-K, 10-Q, 20-F)
• Financial Facts: Access complete financial facts data
• Financial Metrics: Extract key financial metrics for specific periods (annual/quarterly)
  • Total Revenue
  • Net Income
  • Earnings Per Share (EPS)
  • Operating Expenses
  • Operating Cash Flow

Supported Report Types

• 10-K: Annual reports (US companies)
• 10-Q: Quarterly reports (US companies)
• 20-F: Annual reports (Foreign private issuers)

Data Standards

• US-GAAP (US Generally Accepted Accounting Principles)
• IFRS (International Financial Reporting Standards)

API Documentation

Once deployed, visit /docs for interactive Swagger UI documentation or /redoc for ReDoc documentation.

API Endpoints

Basic Endpoints

• POST /api/search_company - Search company by name
• POST /api/get_company_info - Get company information
• POST /api/get_company_filings - Get company filings
• POST /api/get_company_facts - Get company financial facts
• POST /api/get_financial_data - Get financial data for period
• GET /health - Health check

Advanced Endpoints (FinancialAnalyzer)

• POST /api/advanced_search - Advanced search (supports name or CIK)
• POST /api/extract_financial_metrics - Extract multi-year metrics
• POST /api/get_latest_financial_data - Get latest annual data

Usage Example

import requests

BASE_URL = "https://YOUR_SPACE_URL.hf.space"

# IMPORTANT: Use adequate timeout (at least 120 seconds)
# First request after service restart may take 30-60 seconds

# Search company
response = requests.post(
    f"{BASE_URL}/api/search_company",
    json={"company_name": "NVIDIA"},
    timeout=120  # Important!
)
print(response.json())
# Output: {'cik': '0001045810', 'name': 'NVIDIA CORP', 'ticker': 'NVDA'}

# Get financial data
response = requests.post(
    f"{BASE_URL}/api/get_financial_data",
    json={"cik": "0001045810", "period": "2024"},
    timeout=120  # Important!
)
data = response.json()
print(f"Revenue: ${data['total_revenue']:,.0f}")
print(f"Net Income: ${data['net_income']:,.0f}")

Data Source

All data is retrieved from the US Securities and Exchange Commission (SEC) EDGAR system.

User Agent

This service uses the following User-Agent (required by SEC API):

• Juntao Peng Financial Report Metrics App (jtyxabc@gmail.com)

Service Infrastructure

Production Configuration

• Platform: Hugging Face Spaces with CPU Upgrade
• Always-On: Enabled (Don't Sleep mode)
• Process: Single Uvicorn worker (optimized for HF Spaces)
• Health Check: Automatic monitoring every 30 seconds
• Timeout: 75s keep-alive for stable connections
• Concurrency: Up to 200 concurrent requests

Performance Characteristics

• Uptime: 99.9% (always-on mode)
• Response Time: <200ms for cached queries, 1-3s for fresh SEC data
• Rate Limit: Follows SEC guidelines (10 requests/second max)
• Data Freshness: Real-time from SEC EDGAR

Monitoring

Health Check Endpoint:

curl https://jc321-easyreportdatemcp.hf.space/health

Expected response:

{
  "status": "healthy",
  "service": "SEC Financial Report MCP Server"
}

Service Information:

curl https://jc321-easyreportdatemcp.hf.space/

Returns complete API metadata including all endpoints, usage examples, and workflows.