Installation Guide — LISA MCP Server

This guide covers installation on every supported platform: Windows (WSL2), Ubuntu/Debian, Fedora/RHEL, and macOS.

System Requirements
Install on Windows via WSL2
Install on Ubuntu / Debian
Install on Fedora / RHEL / CentOS
Install on macOS
Install the LISA framework itself
Register the MCP server with VS Code
Verify the installation
Upgrading
Uninstalling

1. System Requirements

Component	Minimum Version
Python	3.10
pip	23.0
VS Code	Latest
Git	2.30
OS	Windows 10/11 (WSL2), Ubuntu 20.04+, Fedora 36+, macOS 12+

For running actual tests (optional):

Azure subscription (for Azure platform tests)
SSH key pair for VM access
LISA installed (pip install -e ~/lisa)

For AI failure analysis (optional):

Azure OpenAI API key

2. Install on Windows via WSL2

This project is developed on WSL2. Follow these steps exactly.

2a. Enable WSL2 (if not already done)

Open PowerShell as Administrator:

wsl --install
# Restart your PC when prompted
# After restart, WSL2 installs Ubuntu by default

2b. Open your WSL2 terminal

wsl

2c. Update system packages

sudo apt-get update && sudo apt-get upgrade -y

2d. Install Python 3.10+

# Ubuntu 22.04+ ships Python 3.10 by default
python3 --version
# Python 3.10.x or later — you're good

# If Python 3.9 or earlier:
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt-get update
sudo apt-get install -y python3.12 python3.12-venv python3.12-dev

2e. Install pip

sudo apt-get install -y python3-pip
# or, if that fails:
curl -sS https://bootstrap.pypa.io/get-pip.py | python3 --user

2f. Clone and install

# Clone LISA (the test framework)
git clone https://github.com/microsoft/lisa.git ~/lisa

# Clone this MCP server
git clone https://github.com/kkkashan/LISA_MCP_Server.git ~/lisa-mcp-server

# Install the MCP server
cd ~/lisa-mcp-server
pip3 install -e .

2g. Windows path note

Your Windows home is accessible at /mnt/c/Users/<YourUsername>/ from WSL2. You can store the repos anywhere, but WSL2 paths (e.g. ~/lisa) give much faster I/O than Windows paths (/mnt/c/...).

3. Install on Ubuntu / Debian

# 1. System dependencies
sudo apt-get update
sudo apt-get install -y python3 python3-pip python3-venv git

# 2. Verify Python version
python3 --version # must be 3.10 or later

# 3. Clone repos
git clone https://github.com/microsoft/lisa.git ~/lisa
git clone https://github.com/kkkashan/LISA_MCP_Server.git ~/lisa-mcp-server

# 4. (Recommended) create a virtual environment
python3 -m venv ~/lisa-mcp-server/.venv
source ~/lisa-mcp-server/.venv/bin/activate

# 5. Install
cd ~/lisa-mcp-server
pip install -e .

# 6. Make sure the venv is activated whenever you use the server
# Add to ~/.bashrc:
echo 'source ~/lisa-mcp-server/.venv/bin/activate' >> ~/.bashrc

4. Install on Fedora / RHEL / CentOS

# 1. System dependencies
sudo dnf install -y python3 python3-pip git

# 2. Verify
python3 --version

# 3. Clone repos
git clone https://github.com/microsoft/lisa.git ~/lisa
git clone https://github.com/kkkashan/LISA_MCP_Server.git ~/lisa-mcp-server

# 4. Virtual environment (recommended)
python3 -m venv ~/lisa-mcp-server/.venv
source ~/lisa-mcp-server/.venv/bin/activate

# 5. Install
cd ~/lisa-mcp-server
pip install -e .

5. Install on macOS

# 1. Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Install Python
brew install python@3.12

# 3. Verify
python3 --version

# 4. Clone repos
git clone https://github.com/microsoft/lisa.git ~/lisa
git clone https://github.com/kkkashan/LISA_MCP_Server.git ~/lisa-mcp-server

# 5. Virtual environment (recommended)
python3 -m venv ~/lisa-mcp-server/.venv
source ~/lisa-mcp-server/.venv/bin/activate

# 6. Install
cd ~/lisa-mcp-server
pip install -e .

6. Install the LISA framework itself

This step is required only if you want to run tests. Test discovery, generation, and runbook building work without LISA installed.

# Navigate to the LISA repo
cd ~/lisa

# Install LISA and all its dependencies
pip install -e .

# Verify
lisa --version

LISA system dependencies (Ubuntu/WSL2)

LISA needs some additional packages for test execution:

sudo apt-get install -y \
 gcc \
 libssl-dev \
 libffi-dev \
 build-essential \
 sshpass \
 openssh-client

Azure credentials setup (for Azure tests)

# Install Azure CLI
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

# Login
az login

# Set default subscription
az account set --subscription "YOUR_SUBSCRIPTION_ID"

# Generate SSH key for VM access (if you don't have one)
ssh-keygen -t rsa -b 4096 -f ~/.ssh/lisa_id_rsa -N ""

7. Register the MCP server with VS Code

The repository ships with .vscode/mcp.json already configured. When you open the workspace in VS Code it will detect the server automatically and show a Start button.

Manual setup

If you cloned to a custom location, update .vscode/mcp.json:

# Get the absolute path
REPO_PATH=$(cd ~/lisa-mcp-server && pwd)
echo "Use this path: $REPO_PATH"

Edit .vscode/mcp.json:

{
 "servers": {
 "lisa": {
 "command": "python3",
 "args": ["-m", "lisa_mcp.server"],
 "cwd": "/home/YOUR_USER/lisa-mcp-server"
 }
 }
}

If using a virtual environment

Point command to the venv's Python:

{
 "servers": {
 "lisa": {
 "command": "/home/YOUR_USER/lisa-mcp-server/.venv/bin/python3",
 "args": ["-m", "lisa_mcp.server"],
 "cwd": "/home/YOUR_USER/lisa-mcp-server"
 }
 }
}

If you already have other MCP servers

Merge the lisa key into your existing servers object:

{
 "servers": {
 "existing-server": { "...": "..." },
 "lisa": {
 "command": "python3",
 "args": ["-m", "lisa_mcp.server"],
 "cwd": "/home/YOUR_USER/lisa-mcp-server"
 }
 }
}

Starting the server

Open the Command Palette in VS Code → MCP: Start Server → lisa.

Or click the Start CodeLens button that appears above the server entry in .vscode/mcp.json.

8. Verify the installation

Test a tool directly

In VS Code Copilot Chat:

Using the LISA MCP server, call check_lisa_environment

Expected:

{
 "installed": false,
 "path": null,
 "version_output": ""
}

(installed: true if LISA is installed.)

Test discovery (no LISA needed)

List all test areas in ~/lisa

Expected: a JSON list of area names like ["network", "storage", "cpu", ...].

Full smoke test

python3 -c "
from lisa_mcp.server import mcp
tools = mcp._tool_manager.list_tools()
print(f'Server: {mcp.name}')
print(f'Tools registered: {len(tools)}')
for t in tools:
 print(f' {t.name}')
"

Expected output:

Server: lisa-mcp-server
Tools registered: 17
 discover_test_cases
 list_test_areas
 get_test_case_details
 search_tests
 generate_test_suite_code
 build_runbook
 build_tier_runbook_file
 validate_runbook_file
 add_test_to_existing_runbook
 run_lisa_tests
 parse_test_results
 check_lisa_environment
 get_tier_info
 analyze_test_run_with_llm
 analyze_failure_root_cause
 generate_analysis_report
 run_and_analyze

9. Upgrading

cd ~/lisa-mcp-server

# Pull latest changes
git pull origin main

# Reinstall (editable install updates automatically, but reinstall if pyproject.toml changed)
pip install -e .

# Restart the MCP server in VS Code (Command Palette → MCP: Restart Server)

10. Uninstalling

# Remove the package
pip uninstall lisa-mcp-server

# Remove repos (optional)
rm -rf ~/lisa-mcp-server

# Remove the MCP server registration
# Edit .vscode/mcp.json and remove the "lisa" key

Dependency Reference

All dependencies are declared in pyproject.toml and installed automatically:

Package	Purpose
`mcp>=1.0.0`	Model Context Protocol SDK (FastMCP)
`pyyaml>=6.0`	Parse and generate runbook YAML
`pydantic>=2.0`	Data validation for models
`rich>=13.0`	Terminal formatting
`click>=8.0`	CLI entry point
`junitparser>=3.0`	Parse JUnit XML test results
`httpx>=0.27.0`	HTTP client for Azure OpenAI API calls

Troubleshooting Installation

See docs/troubleshooting.md for common issues.

Quick fixes:

# "ModuleNotFoundError: No module named 'lisa_mcp'"
pip install -e ~/lisa-mcp-server

# "command not found: python3"
sudo apt-get install python3 # Ubuntu
brew install python@3.12 # macOS

# MCP server shows as "disconnected" in VS Code
# Check the cwd path is absolute and the Python path is correct
python3 ~/lisa-mcp-server/lisa_mcp/server.py # run directly to see errors

# Azure OpenAI API errors
# Verify your API key and that the endpoint URL is reachable
curl -s -H "api-key: YOUR_KEY" \
 "https://kkopenailearn.openai.azure.com/openai/models?api-version=2025-04-01-preview" | python3 -m json.tool

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Installation Guide — LISA MCP Server

Table of Contents

1. System Requirements

2. Install on Windows via WSL2

2a. Enable WSL2 (if not already done)

2b. Open your WSL2 terminal

2c. Update system packages

2d. Install Python 3.10+

2e. Install pip

2f. Clone and install

2g. Windows path note

3. Install on Ubuntu / Debian

4. Install on Fedora / RHEL / CentOS

5. Install on macOS

6. Install the LISA framework itself

LISA system dependencies (Ubuntu/WSL2)

Azure credentials setup (for Azure tests)

7. Register the MCP server with VS Code

Manual setup

If using a virtual environment

If you already have other MCP servers

Starting the server

8. Verify the installation

Test a tool directly

Test discovery (no LISA needed)

Full smoke test

9. Upgrading

10. Uninstalling

Dependency Reference

Troubleshooting Installation

FilesExpand file tree

INSTALL.md

Latest commit

History

INSTALL.md

File metadata and controls

Installation Guide — LISA MCP Server

Table of Contents

1. System Requirements

2. Install on Windows via WSL2

2a. Enable WSL2 (if not already done)

2b. Open your WSL2 terminal

2c. Update system packages

2d. Install Python 3.10+

2e. Install pip

2f. Clone and install

2g. Windows path note

3. Install on Ubuntu / Debian

4. Install on Fedora / RHEL / CentOS

5. Install on macOS

6. Install the LISA framework itself

LISA system dependencies (Ubuntu/WSL2)

Azure credentials setup (for Azure tests)

7. Register the MCP server with VS Code

Manual setup

If using a virtual environment

If you already have other MCP servers

Starting the server

8. Verify the installation

Test a tool directly

Test discovery (no LISA needed)

Full smoke test

9. Upgrading

10. Uninstalling

Dependency Reference

Troubleshooting Installation