QuantConnect MCP Server

Instructions

Implementation Reference

• quantconnect_mcp/src/tools/project_tools.py:127-222 (handler)

  Core handler implementation for the 'read_project' MCP tool. Decorated with @mcp.tool(), it handles authentication, API calls to QuantConnect's 'projects/read' endpoint, and parses responses for single project or list of projects.

  @mcp.tool()
  async def read_project(project_id: Optional[int] = None) -> Dict[str, Any]:
      """
      Read project details by ID or list all projects if no ID provided.
  
      Args:
          project_id: Optional project ID to get specific project details.
                     If not provided, returns list of all projects.
  
      Returns:
          Dictionary containing project details or list of all projects
      """
      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 = {}
          if project_id is not None:
              request_data["projectId"] = project_id
  
          # Make API request
          response = await auth.make_authenticated_request(
              endpoint="projects/read", method="POST", json=request_data
          )
  
          # Parse response
          if response.status_code == 200:
              data = response.json()
  
              if data.get("success", False):
                  projects = data.get("projects", [])
                  versions = data.get("versions", [])
  
                  # If specific project ID was requested
                  if project_id is not None:
                      if projects:
                          return {
                              "status": "success",
                              "project": projects[0],
                              "versions": versions,
                              "message": f"Successfully retrieved project {project_id}",
                          }
                      else:
                          return {
                              "status": "error",
                              "error": f"Project with ID {project_id} not found",
                          }
  
                  # If no project ID specified, return all projects
                  else:
                      return {
                          "status": "success",
                          "projects": projects,
                          "total_projects": len(projects),
                          "versions": versions,
                          "message": f"Successfully retrieved {len(projects)} projects",
                      }
              else:
                  # API returned success=false
                  errors = data.get("errors", ["Unknown error"])
                  return {
                      "status": "error",
                      "error": "Failed to read project(s)",
                      "details": errors,
                      "api_response": data,
                  }
  
          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 project(s): {str(e)}",
              "project_id": project_id,
          }

• quantconnect_mcp/main.py:47-52 (registration)

  Top-level registration call to register_project_tools(mcp), which registers the read_project tool among other project management tools with the FastMCP server instance.

  register_auth_tools(mcp)
  register_project_tools(mcp)
  register_file_tools(mcp)
  register_backtest_tools(mcp)
  register_live_tools(mcp)
  register_optimization_tools(mcp)

• quantconnect_mcp/src/tools/project_tools.py:128-138 (schema)

  Type hints and documentation defining the tool schema: input 'project_id' (Optional[int]), output Dict[str, Any].

  async def read_project(project_id: Optional[int] = None) -> Dict[str, Any]:
      """
      Read project details by ID or list all projects if no ID provided.
  
      Args:
          project_id: Optional project ID to get specific project details.
                     If not provided, returns list of all projects.
  
      Returns:
          Dictionary containing project details or list of all projects
      """