QuantConnect MCP Server

Instructions

Implementation Reference

• quantconnect_mcp/src/tools/backtest_tools.py:225-350 (handler)

  The primary handler function for the 'read_backtest_chart' tool. Decorated with @mcp.tool(), it authenticates via QuantConnect API, prepares request parameters, calls the 'backtests/chart/read' endpoint, and returns chart data or loading progress.

  @mcp.tool()
  async def read_backtest_chart(
      project_id: int,
      backtest_id: str,
      name: str,
      count: int = 100,
      start: Optional[int] = None,
      end: Optional[int] = None,
  ) -> Dict[str, Any]:
      """
      Read chart data from a backtest.
  
      Args:
          project_id: Project ID containing the backtest
          backtest_id: ID of the backtest to get chart from
          name: Name of the chart to retrieve (e.g., "Strategy Equity")
          count: Number of data points to request (default: 100)
          start: Optional UTC start timestamp in seconds
          end: Optional UTC end timestamp in seconds
  
      Returns:
          Dictionary containing chart data or loading status
      """
      auth = get_auth_instance()
      if auth is None:
          return {
              "status": "error",
              "error": "QuantConnect authentication not configured. Use configure_auth() first.",
          }
  
      try:
          # Prepare request data
          request_data = {
              "projectId": project_id,
              "backtestId": backtest_id,
              "name": name,
              "count": count,
          }
  
          # Add optional timestamp parameters
          if start is not None:
              request_data["start"] = start
          if end is not None:
              request_data["end"] = end
  
          # Make API request
          response = await auth.make_authenticated_request(
              endpoint="backtests/chart/read", method="POST", json=request_data
          )
  
          # Parse response
          if response.status_code == 200:
              data = response.json()
  
              if data.get("success", False):
                  # Check if chart is still loading
                  if "progress" in data and "status" in data:
                      progress = data.get("progress", 0)
                      status = data.get("status", "loading")
                      return {
                          "status": "loading",
                          "project_id": project_id,
                          "backtest_id": backtest_id,
                          "chart_name": name,
                          "progress": progress,
                          "chart_status": status,
                          "message": f"Chart '{name}' is loading... ({progress * 100:.1f}% complete)",
                      }
  
                  # Chart is ready
                  elif "chart" in data:
                      chart = data.get("chart")
                      return {
                          "status": "success",
                          "project_id": project_id,
                          "backtest_id": backtest_id,
                          "chart_name": name,
                          "chart": chart,
                          "count": count,
                          "start": start,
                          "end": end,
                          "message": f"Successfully retrieved chart '{name}' from backtest {backtest_id}",
                      }
  
                  else:
                      return {
                          "status": "error",
                          "error": "Unexpected response format - no chart or progress data found",
                      }
              else:
                  # API returned success=false
                  errors = data.get("errors", ["Unknown error"])
                  return {
                      "status": "error",
                      "error": "Failed to read backtest chart",
                      "details": errors,
                      "project_id": project_id,
                      "backtest_id": backtest_id,
                      "chart_name": name,
                  }
  
          elif response.status_code == 401:
              return {
                  "status": "error",
                  "error": "Authentication failed. Check your credentials and ensure they haven't expired.",
              }
  
          else:
              return {
                  "status": "error",
                  "error": f"API request failed with status {response.status_code}",
                  "response_text": (
                      response.text[:500]
                      if hasattr(response, "text")
                      else "No response text"
                  ),
              }
  
      except Exception as e:
          return {
              "status": "error",
              "error": f"Failed to read backtest chart: {str(e)}",
              "project_id": project_id,
              "backtest_id": backtest_id,
              "chart_name": name,
          }

• quantconnect_mcp/src/server.py:77-77 (registration)

  Invocation of register_backtest_tools(mcp) which defines and registers the read_backtest_chart tool (via nested @mcp.tool() decorator) with the FastMCP server instance.

  register_backtest_tools(mcp)