bioos

The Bio-OS MCP Server provides a model-context protocol based interface for Bio-OS workflow management and Docker image building. It is intended to be used via the CLINE extension in VSCode, either running locally or through Code Server in Miracle Cloud. The server exposes a set of tools for submitting and managing Bio-OS workflows, uploading WDL files, validating workflows, generating input templates, and handling Docker image builds and related status checks. In practice, you would configure the MCP server in your editor by pointing to the uv runner with the appropriate directory and server script, supply the necessary environment variables (such as PYTHONPATH and Miracle Cloud credentials), and then use the provided tools to interact with Bio-OS resources. The available API tools include submit_workflow, import_workflow, validate_wdl, generate_inputs, build_docker_image, check_build_status, download_gse_data, and get_gse_download_status, enabling end-to-end workflow management and image building directly from the editor. Note that prompts are not supported in the current CLINE setup, so you would rely on the built-in tools and the bioos_mcp_server.py prompts when running the server directly.

Prerequisites: Python with uv installed, and optionally Cromwell for workflow execution.

Step 1: Install prerequisites

• Install uv (Python package manager):

  pip install uv
  

• Install Cromwell (Workflow execution engine):

  brew install cromwell
  

Step 2: Clone the repository

• Clone the Bio-OS MCP Server repository:

  git clone https://github.com/GBA-BI/bioos-mcp-server.git
  

Step 3: Configure MCP for local usage

• In your editor (e.g., VSCode with CLINE), configure the Bio-OS MCP Server using the following example configuration. Replace placeholders with absolute paths to your installation:

  {
    "mcpServers": {
      "bioos": {
        "command": "path/to/uv",
        "args": [
          "--directory",
          "path/to/bioos-mcp-server",
          "run",
          "path/to/bioos-mcp-server/src/bioos_mcp/bioos_mcp_server.py"
        ],
        "env": {
          "PYTHONPATH": "path/to/bioos-mcp-server/src",
          "MIRACLE_ACCESS_KEY": "xxxxxxxxxxxx",
          "MIRACLE_SECRET_KEY": "xxxxxxxxxxxx"
        }
      }
    }
  }
  

Step 4: Start or connect to the MCP server

• Use your editor’s MCP integration (e.g., CLINE) to run the configured Bio-OS MCP Server. Ensure the status turns green and that the connection is stable. If needed, use the Retry Connection option.

Optional: Cloud deployment through Code Server in Miracle Cloud is described in the README and uses a pre-configured Docker image. The steps above cover the local installation path.

Tips and notes:

• Ensure you have PYTHONPATH set to the server source directory so the Bio-OS MCP Server modules are importable by uv.
• If you’re using Miracle Cloud, you’ll rely on the provided Docker image and Code Server integration; the README mentions specific Miracle Cloud images and steps for launching IES and opening Code Server.
• When configuring through CLINE, you may need to provide MIRACLE_ACCESS_KEY and MIRACLE_SECRET_KEY for authentication.
• The prompts listed in the API reference are not yet supported within the CLINE environment; you can use them when running the MCP server directly or via Claude Desktop.
• If the connection is unstable, use the editor’s Retry Connection feature.
• For WDL-related tasks, you can still use tools like validate_wdl, generate_inputs, and import_workflow to manage WDL scripts and templates.
• Building Docker images through the server requires supplying registry, namespace, repository, and tag, plus a path to the Dockerfile or artifact to build from.