# Install WebAccess.MCP, Podman Desktop, and LM Studio on a New Windows PC This guide is for a person starting with a Windows computer that does not yet have Podman Desktop, LM Studio, or WebAccess.MCP installed. PowerShell privilege labels in this guide mean: - **PowerShell (Standard user)**: open PowerShell normally. - **PowerShell (Admin)**: right-click PowerShell and select **Run as administrator**. Use standard-user PowerShell unless a step is explicitly labeled **PowerShell (Admin)**. For a shorter operations-only guide that assumes Podman and the repository are already installed, see `docs\Standing-Up-the-Podman-Compose-Stack.md`. For a focused, step-by-step LM Studio MCP configuration guide, see `docs\Adding-WebAccess-MCP-to-LM-Studio.md`. It creates one predictable AI workspace on a drive of your choice: ```text :\ai\ llm\ models\ LM Studio model files mcp\ WebAccess.MCP\ This MCP server and its deployment files ``` For example, if `D:` has enough free space: ```text D:\ai\llm\models D:\ai\mcp\WebAccess.MCP ``` The examples below use `D:`. Substitute another local drive everywhere if needed. Use the same drive consistently. > Podman Desktop and LM Studio are normal Windows applications, so their > executables and application settings are installed in Windows-managed > locations. Podman also stores container images and volumes inside its managed > Linux virtual machine. The model files, MCP source, and deployment > configuration are organized beneath `:\ai`. ## What This Installation Provides Podman Compose runs three containers: - `webaccess`: the .NET 10 MCP server, Playwright, and headless Chromium. - `searxng`: the dedicated search service used by `web_search`. - `postgres`: durable page-cache storage. LM Studio connects to WebAccess.MCP through Streamable HTTP at: ```text http://127.0.0.1:28081/mcp ``` SearXNG is available for local diagnostics at: ```text http://127.0.0.1:28080/ ``` Both ports bind only to the local computer, not to the LAN. ## Before You Begin You need: - 64-bit Windows 10 build 19043 or later, or Windows 11. - Administrator access for enabling WSL 2. - Hardware virtualization enabled in the computer's BIOS or UEFI. - At least 6 GB of RAM available to the Podman machine. More RAM is strongly recommended because LM Studio must run a model at the same time. - Enough free disk space for Podman images and one or more LLMs. Models commonly consume several to tens of gigabytes each. - Internet access during installation, image building, and model download. - A trusted copy of the WebAccess.MCP repository. The optional integration TestRig also requires the .NET 10 SDK. It is not required for normal use because WebAccess.MCP builds inside a container. ## 1. Choose the AI Drive and Create the Folder Layout Choose a local drive with enough free space. Avoid a network share, removable drive, OneDrive, or another synchronized folder. **PowerShell (Standard user)** ```powershell $AiDrive = "D:" $AiRoot = Join-Path $AiDrive "ai" New-Item -ItemType Directory -Force -Path ` (Join-Path $AiRoot "llm\models"), ` (Join-Path $AiRoot "mcp") ``` Verify the layout: ```powershell Get-ChildItem $AiRoot -Recurse ``` Keep `$AiRoot` set in this PowerShell window while completing the installation. In a new PowerShell window, set it again: ```powershell $AiRoot = "D:\ai" ``` ## 2. Install WSL 2 Podman uses a small Linux virtual machine on Windows. WSL 2 is the recommended provider. **PowerShell (Admin)** ```powershell wsl --install --no-distribution ``` Restart Windows if prompted. After restarting, open PowerShell and verify WSL: ```powershell wsl --status ``` If WSL installation fails, confirm that virtualization is enabled in BIOS/UEFI and that Windows is fully updated before continuing. ## 3. Install and Configure Podman Desktop ### Install the application Use either method below. **Option A: Windows Package Manager** Open PowerShell and run: ```powershell winget install --exact --id RedHat.Podman-Desktop ``` **Option B: Windows installer** 1. Download Podman Desktop from [podman-desktop.io/downloads](https://podman-desktop.io/downloads). 2. Run the downloaded installer. 3. Choose whether to install it for the current user or all users. 4. Complete the installer and start Podman Desktop. ### Complete Podman Desktop onboarding In Podman Desktop: 1. Select **Start Onboarding**. 2. Allow Podman Desktop to install the Podman engine. 3. Keep **WSL 2** selected as the machine provider. 4. Create the Podman machine when prompted. 5. Install the Compose CLI when prompted. 6. Complete onboarding and open the dashboard. If onboarding was previously skipped: 1. Open **Settings > Resources**. 2. In the **Podman** tile, select **Setup Podman**. 3. Create and start a WSL-based Podman machine. 4. In the **Compose** tile, select **Setup**. The official Podman Desktop minimum is 6 GB of RAM for its machine. If the computer has sufficient memory, assign more resources in Podman Desktop so Chromium, PostgreSQL, and SearXNG can run comfortably alongside LM Studio. Open a new PowerShell window and verify both components: ```powershell podman info podman compose version ``` Do not continue until both commands succeed. If `podman info` cannot connect, open Podman Desktop and start its Podman machine. ## 4. Install LM Studio and Set Its Model Folder 1. Download LM Studio for Windows from [lmstudio.ai/download](https://lmstudio.ai/download). 2. Run the installer and start LM Studio. 3. Complete the initial setup. 4. Open **My Models** in LM Studio. 5. Use the model-directory control to change the models directory to: ```text D:\ai\llm\models ``` LM Studio may create organization and model subdirectories beneath this folder. Do not manually flatten those directories. WebAccess.MCP requires LM Studio 0.3.17 or later. Check the installed version in LM Studio and install any offered update before configuring MCP. ## 5. Put WebAccess.MCP Under the AI Folder The final repository location must be: ```text D:\ai\mcp\WebAccess.MCP ``` Use one of the following methods. ### Option A: Copy a supplied folder If WebAccess.MCP was supplied as a folder, copy the entire folder into: ```text D:\ai\mcp\ ``` Do not copy only the `deploy` directory. The container build also needs the production source beneath `src`. ### Option B: Extract a supplied ZIP file Extract the ZIP and move or rename the extracted repository folder so that this file exists: ```text D:\ai\mcp\WebAccess.MCP\deploy\compose.yml ``` Avoid an accidental double folder such as: ```text D:\ai\mcp\WebAccess.MCP\WebAccess.MCP\deploy\compose.yml ``` ### Option C: Clone with Git If the person distributing WebAccess.MCP provides a Git repository URL, install Git and clone it: ```powershell winget install --exact --id Git.Git ``` Close and reopen PowerShell after Git installation, then run: ```powershell $AiRoot = "D:\ai" Set-Location (Join-Path $AiRoot "mcp") git clone WebAccess.MCP ``` Replace `` with the trusted URL supplied by the project owner. ### Verify the repository ```powershell $AiRoot = "D:\ai" $WebAccessRoot = Join-Path $AiRoot "mcp\WebAccess.MCP" Test-Path (Join-Path $WebAccessRoot "deploy\compose.yml") Test-Path (Join-Path $WebAccessRoot "Containerfile") Test-Path (Join-Path $WebAccessRoot "src\WebAccess.MCP\WebAccess.MCP.csproj") ``` All three commands must return `True`. ## 6. Create Installation Secrets WebAccess.MCP needs a local PostgreSQL password and SearXNG secret. Generate unique values rather than copying secrets from another computer. Open PowerShell and run: ```powershell $AiRoot = "D:\ai" $DeployRoot = Join-Path $AiRoot "mcp\WebAccess.MCP\deploy" Set-Location $DeployRoot function New-HexSecret { $bytes = New-Object byte[] 32 $generator = [System.Security.Cryptography.RandomNumberGenerator]::Create() try { $generator.GetBytes($bytes) } finally { $generator.Dispose() } -join ($bytes | ForEach-Object { $_.ToString("x2") }) } @" WEBACCESS_POSTGRES_PASSWORD=$(New-HexSecret) SEARXNG_SECRET=$(New-HexSecret) "@ | Set-Content -Encoding Ascii .env ``` Verify that the file exists without printing its secret values: ```powershell Test-Path .env ``` The repository ignores `deploy\.env`. Keep it private, do not send it to anyone, and do not commit it to Git. ## 7. Build and Start WebAccess.MCP From `D:\ai\mcp\WebAccess.MCP\deploy`, run: ```powershell .\Start-WebAccessStack.ps1 ``` The script creates `deploy\.env` with random installation secrets if needed, verifies Podman and Compose, and runs the entire Compose stack. The first run downloads the base images and builds WebAccess.MCP. It can take several minutes because the Playwright image includes Chromium and its Linux dependencies. Check the services: ```powershell podman compose --project-name webaccess-mcp ps ``` Expected result: - `postgres` is running and healthy. - `searxng` is running and healthy. - `webaccess` is running. Compose waits for PostgreSQL and SearXNG to become healthy before starting WebAccess.MCP. In Podman Desktop, open **Containers**. The three services should appear in a `webaccess-mcp (compose)` group. Expand the group to inspect status, ports, and logs. If a service does not start: ```powershell podman compose --project-name webaccess-mcp logs --tail 200 ``` ## 8. Verify the Running Services Verify both local ports: ```powershell Test-NetConnection 127.0.0.1 -Port 28080 Test-NetConnection 127.0.0.1 -Port 28081 ``` Both results should include: ```text TcpTestSucceeded : True ``` Verify the dedicated SearXNG instance: ```powershell (Invoke-RestMethod "http://127.0.0.1:28080/config").instance_name ``` The expected name is: ```text WebAccess.MCP SearXNG ``` The `/mcp` URL is a protocol endpoint, not a normal website. Opening it in a browser is not a complete MCP test. LM Studio will perform the MCP handshake in a later step. ## 9. Download a Tool-Capable Model in LM Studio WebAccess.MCP supplies tools, but the selected language model decides when and how to call them. Choose an **instruct/chat model with tool-use or function-call support**. A plain base model is not suitable. In LM Studio: 1. Open **Discover** (`Ctrl+2`). 2. Search for a tool-capable instruct model appropriate for the computer. 3. Select a GGUF quantization. A 4-bit option is a practical starting point for many computers; larger quantizations need more RAM or VRAM. 4. Download the model. 5. Confirm in **My Models** that it was stored beneath: ```text D:\ai\llm\models ``` 6. Open **Chat** and load the model. Prefer a model with enough context for tool schemas and returned web content. At least 16K context is a useful starting point when the model and hardware support it. Model availability changes frequently, so this guide does not lock the installation to one model family. If LM Studio cannot use MCP tools reliably with the chosen model, first confirm that the model card advertises tool/function calling. Then try a stronger instruct model or a less aggressive quantization if the hardware permits. ## 10. Introduce WebAccess.MCP to LM Studio LM Studio 0.3.17 and later supports remote MCP servers by URL. 1. Keep the Podman stack running. 2. In LM Studio, open the **Program** tab in the right sidebar. 3. Select **Install > Edit mcp.json**. 4. If the file is empty, enter: ```json { "mcpServers": { "webaccess": { "url": "http://127.0.0.1:28081/mcp" } } } ``` If the file already contains MCP servers, add only this property inside its existing `mcpServers` object: ```json "webaccess": { "url": "http://127.0.0.1:28081/mcp" } ``` Preserve the existing entries and include commas between JSON properties. This is a remote Streamable HTTP MCP server: - Do not add `command` or `args`. - Do not add authentication headers. - Do not use `http://127.0.0.1:28080`; that is SearXNG, not MCP. - Do not use `localhost` if local security software resolves it unexpectedly; use the exact `127.0.0.1` URL shown above. 5. Save `mcp.json`. 6. Confirm that `webaccess` appears and is enabled in the Program tab. 7. Start or return to a chat with the tool-capable model loaded. 8. Enable the WebAccess.MCP tools for that chat if LM Studio asks. ## 11. Test LM Studio and WebAccess.MCP Together Ask the model: > Use `web_search` to find the official LM Studio MCP documentation. Return the > page title and source URL. LM Studio should display a `web_search` tool call and its result. Then test the browser tools: > Open the official LM Studio MCP documentation URL, report the page title, and > list the first five links. WebAccess.MCP has 15 tools. LM Studio should show those tools as available when the MCP connection is healthy. The browser context is intentionally long-lived. Navigation and interaction state persist across tool calls even though the MCP HTTP transport is stateless. ## 12. Start and Stop the System ### Start a normal session 1. Start Podman Desktop. 2. Make sure the Podman machine is running. 3. Open PowerShell and run: ```powershell Set-Location "D:\ai\mcp\WebAccess.MCP\deploy" podman compose --project-name webaccess-mcp up --detach ``` 4. Start LM Studio. 5. Load the desired tool-capable model. 6. Confirm that `webaccess` is enabled in the Program tab. ### Stop a normal session Close LM Studio if desired, then run: ```powershell Set-Location "D:\ai\mcp\WebAccess.MCP\deploy" podman compose --project-name webaccess-mcp stop ``` This preserves the containers and PostgreSQL page cache. ### Start the stopped containers again ```powershell Set-Location "D:\ai\mcp\WebAccess.MCP\deploy" podman compose --project-name webaccess-mcp start ``` ### Remove containers but preserve data ```powershell Set-Location "D:\ai\mcp\WebAccess.MCP\deploy" podman compose --project-name webaccess-mcp down ``` This removes the containers and private network but preserves the PostgreSQL volume. ## 13. Update WebAccess.MCP Before updating, stop the stack: ```powershell Set-Location "D:\ai\mcp\WebAccess.MCP\deploy" podman compose --project-name webaccess-mcp down ``` Replace the supplied repository files with the newer version, or use Git: ```powershell Set-Location "D:\ai\mcp\WebAccess.MCP" git pull ``` Do not overwrite or delete `deploy\.env`. Rebuild and start: ```powershell Set-Location "D:\ai\mcp\WebAccess.MCP\deploy" podman compose --project-name webaccess-mcp up --detach --build ``` The LM Studio `mcp.json` entry does not need to change as long as the endpoint remains `http://127.0.0.1:28081/mcp`. ## 14. Optional Full Integration Test This section is for maintainers or advanced troubleshooting. Install the .NET 10 SDK, keep the stack running, and execute from the repository root: ```powershell Set-Location "D:\ai\mcp\WebAccess.MCP" dotnet run --project ".\src\WebAccess.MCP.TestRig\WebAccess.MCP.TestRig.csproj" -- ` --mcp-url "http://127.0.0.1:28081/mcp" ` --real-searxng ` --real-searxng-engine google ` --real-searxng-engine brave ` --real-searxng-engine duckduckgo ``` The TestRig validates the HTTP MCP transport, the 15-tool contract, browser state and interactions, page caching, and the externally managed SearXNG service. External providers can still rate-limit or challenge automated search requests. ## 15. Troubleshooting ### Podman commands are not recognized Close and reopen PowerShell after installing Podman Desktop. If the commands remain unavailable, return to Podman Desktop onboarding or **Settings > Resources** and install Podman and Compose. ### Podman cannot connect Open Podman Desktop and start the Podman machine. Then retry: ```powershell podman info ``` If the machine cannot start, verify WSL 2: ```powershell wsl --status ``` ### LM Studio cannot connect to WebAccess.MCP 1. Confirm LM Studio is version 0.3.17 or later. 2. Confirm the URL is exactly `http://127.0.0.1:28081/mcp`. 3. Confirm `webaccess` is enabled in LM Studio's Program tab. 4. Run: ```powershell Set-Location "D:\ai\mcp\WebAccess.MCP\deploy" podman compose --project-name webaccess-mcp ps Test-NetConnection 127.0.0.1 -Port 28081 podman compose --project-name webaccess-mcp logs --tail 200 webaccess ``` 5. Check that `mcp.json` is valid JSON. ### A host port is already in use Identify the owning process: ```powershell Get-NetTCPConnection -State Listen -LocalPort 28080,28081 | Select-Object -Property LocalAddress, LocalPort, OwningProcess ``` Stop or reconfigure the conflicting application. Do not substitute port 18080; that port belongs to an unrelated deployment. ### PostgreSQL rejects the password after `.env` was changed PostgreSQL initializes its password only when its data volume is first created. Restore the original `WEBACCESS_POSTGRES_PASSWORD`. If the password is lost and deleting the WebAccess.MCP page cache is acceptable, perform an intentional reset: ```powershell Set-Location "D:\ai\mcp\WebAccess.MCP\deploy" podman compose --project-name webaccess-mcp down --volumes podman compose --project-name webaccess-mcp up --detach --build ``` `down --volumes` permanently deletes this stack's PostgreSQL data. Do not use it for normal shutdown. ### Search fails while browser tools work 1. Open `http://127.0.0.1:28080/config`. 2. Inspect the `searxng` and `webaccess` logs in Podman Desktop. 3. Confirm the dedicated SearXNG service is healthy. External search engines can temporarily fail, rate-limit requests, or present anti-bot challenges. WebAccess.MCP does not bypass those restrictions. ### The Compose group is missing in Podman Desktop Confirm Podman Desktop is connected to the same Podman machine used by PowerShell. Starting with the exact `--project-name webaccess-mcp` command adds the Compose labels Podman Desktop uses to display the services as one group. ### LM Studio saves models somewhere else Return to **My Models**, change the model directory to `D:\ai\llm\models`, and use LM Studio's own directory controls to move or redownload models. Do not manually reorganize a model while LM Studio is running.