QuantConnect MCP Server

Instructions

Implementation Reference

• quantconnect_mcp/src/tools/backtest_tools.py:11-128 (handler)

  The core implementation of the 'create_backtest' tool. This async function, decorated with @mcp.tool(), handles authentication, constructs the API request to QuantConnect's backtests/create endpoint, processes parameters, and returns structured success/error responses with backtest details.

  @mcp.tool()
  async def create_backtest(
      project_id: int,
      compile_id: str,
      backtest_name: str,
      parameters: Optional[Dict[str, Any]] = None,
  ) -> Dict[str, Any]:
      """
      Create a new backtest for a compiled project.
  
      Args:
          project_id: ID of the project to backtest
          compile_id: Compile ID from a successful project compilation
          backtest_name: Name for the backtest
          parameters: Optional dictionary of parameters for the backtest (e.g., {"ema_fast": 10, "ema_slow": 100})
  
      Returns:
          Dictionary containing backtest creation result and backtest details
      """
      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,
              "compileId": compile_id,
              "backtestName": backtest_name,
          }
  
          # Add parameters if provided
          if parameters:
              for key, value in parameters.items():
                  request_data[f"parameters[{key}]"] = value
  
          # Make API request
          response = await auth.make_authenticated_request(
              endpoint="backtests/create", method="POST", json=request_data
          )
  
          # Parse response
          if response.status_code == 200:
              data = response.json()
  
              if data.get("success", False):
                  backtest_results = data.get("backtest", [])
                  debugging = data.get("debugging", False)
  
                  if backtest_results:
                      backtest = backtest_results[0]
                      return {
                          "status": "success",
                          "project_id": project_id,
                          "compile_id": compile_id,
                          "backtest_name": backtest_name,
                          "backtest": backtest,
                          "debugging": debugging,
                          "message": f"Successfully created backtest '{backtest_name}' for project {project_id}",
                      }
                  else:
                      return {
                          "status": "success",
                          "project_id": project_id,
                          "compile_id": compile_id,
                          "backtest_name": backtest_name,
                          "debugging": debugging,
                          "message": f"Backtest '{backtest_name}' created but no results yet",
                          "note": "Backtest may still be initializing",
                      }
              else:
                  # API returned success=false
                  errors = data.get("errors", ["Unknown error"])
                  if any("Compile id not found" in e for e in errors):
                      return {
                          "status": "error",
                          "error": "Compile ID not found. Please compile the project first using the 'compile_project' tool.",
                          "details": errors,
                          "project_id": project_id,
                          "compile_id": compile_id,
                      }
                  return {
                      "status": "error",
                      "error": "Backtest creation failed",
                      "details": errors,
                      "project_id": project_id,
                      "compile_id": compile_id,
                      "backtest_name": backtest_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 create backtest: {str(e)}",
              "project_id": project_id,
              "compile_id": compile_id,
              "backtest_name": backtest_name,
          }

• quantconnect_mcp/main.py:50-50 (registration)

  Top-level registration call in the main entry point that invokes register_backtest_tools(mcp), thereby registering the 'create_backtest' handler to the FastMCP server.

  register_backtest_tools(mcp)

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

  Registration call in the server module that registers backtest tools including 'create_backtest' to the MCP instance.

  register_backtest_tools(mcp)

• quantconnect_mcp/src/tools/backtest_tools.py:12-29 (schema)

  Function signature and docstring defining the input schema (parameters: project_id, compile_id, backtest_name, optional parameters dict) and output (Dict[str, Any] with status, details, etc.).

  async def create_backtest(
      project_id: int,
      compile_id: str,
      backtest_name: str,
      parameters: Optional[Dict[str, Any]] = None,
  ) -> Dict[str, Any]:
      """
      Create a new backtest for a compiled project.
  
      Args:
          project_id: ID of the project to backtest
          compile_id: Compile ID from a successful project compilation
          backtest_name: Name for the backtest
          parameters: Optional dictionary of parameters for the backtest (e.g., {"ema_fast": 10, "ema_slow": 100})
  
      Returns:
          Dictionary containing backtest creation result and backtest details
      """