get_filings
Fetch SEC filing metadata for companies to access 10-Q, 10-K, and 8-K reports with URLs, dates, and fiscal period information.
Instructions
Fetch SEC filing metadata for a company. Returns list of 10-Q, 10-K, and 8-K (earnings release) filings with URLs, dates, and fiscal period assignments.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ticker | Yes | ||
| year | Yes | ||
| quarter | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- edgar_mcp/server.py:699-712 (handler)Main async handler function decorated with @mcp.tool() that accepts ticker, year, and quarter parameters. It delegates to _run_tool_guarded with the tool name and arguments.
@mcp.tool() async def get_filings( ticker: str, year: int, quarter: int, ) -> dict: """ Fetch SEC filing metadata for a company. Returns list of 10-Q, 10-K, and 8-K (earnings release) filings with URLs, dates, and fiscal period assignments. """ return await _run_tool_guarded( "get_filings", {"ticker": ticker, "year": year, "quarter": quarter}, ) - edgar_mcp/server.py:315-320 (helper)Proxy function that makes the actual API call to the remote EDGAR API. Calls /api/filings endpoint with ticker, year, and quarter parameters.
def _proxy_get_filings(args: dict) -> dict: return _call_api("/api/filings", { "ticker": args["ticker"], "year": args["year"], "quarter": args["quarter"], }) - edgar_mcp/server.py:647-654 (registration)Tool dispatch dictionary that registers 'get_filings' to its proxy function _proxy_get_filings. Used by _run_tool_guarded to route tool calls.
_TOOL_DISPATCH = { "get_filings": _proxy_get_filings, "get_financials": _proxy_get_financials, "get_metric": _proxy_get_metric, "list_metrics": _proxy_list_metrics, "search_metrics": _proxy_search_metrics, "get_filing_sections": _proxy_get_filing_sections, } - edgar_mcp/server.py:656-663 (registration)Tool timeout configuration that sets a 30-second timeout for get_filings tool execution.
_TOOL_TIMEOUT = { "get_filings": 30, "get_financials": 60, "get_metric": 30, "list_metrics": 45, "search_metrics": 45, "get_filing_sections": 60, } - edgar_mcp/server.py:73-99 (helper)HTTP helper function that makes GET requests to the remote EDGAR API with authentication and error handling.
def _call_api(path: str, params: dict, timeout: int = 60) -> dict: """HTTP GET to the remote EDGAR API. Returns parsed JSON or error dict.""" base_url, api_key = _get_api_config() if not api_key: return {"status": "error", "message": "EDGAR_API_KEY is not configured"} url = f"{base_url}{path}" payload = dict(params) payload["key"] = api_key t0 = time.time() try: resp = requests.get(url, params=payload, timeout=timeout) except requests.RequestException as exc: return {"status": "error", "message": f"EDGAR API request failed after {time.time()-t0:.1f}s: {exc}"} try: data = resp.json() except ValueError: return {"status": "error", "message": f"Invalid JSON from EDGAR API (HTTP {resp.status_code})"} if resp.status_code != 200: if isinstance(data, dict) and data: return data return {"status": "error", "message": f"EDGAR API error (HTTP {resp.status_code})"} return data