edgar-mcp

Instructions

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