18 KiB
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:
<drive>:\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:
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
<drive>:\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 byweb_search.postgres: durable page-cache storage.
LM Studio connects to WebAccess.MCP through Streamable HTTP at:
http://127.0.0.1:28081/mcp
SearXNG is available for local diagnostics at:
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)
$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:
Get-ChildItem $AiRoot -Recurse
Keep $AiRoot set in this PowerShell window while completing the installation.
In a new PowerShell window, set it again:
$AiRoot = "D:\ai"
2. Install WSL 2
Podman uses a small Linux virtual machine on Windows. WSL 2 is the recommended provider.
PowerShell (Admin)
wsl --install --no-distribution
Restart Windows if prompted. After restarting, open PowerShell and verify WSL:
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:
winget install --exact --id RedHat.Podman-Desktop
Option B: Windows installer
- Download Podman Desktop from podman-desktop.io/downloads.
- Run the downloaded installer.
- Choose whether to install it for the current user or all users.
- Complete the installer and start Podman Desktop.
Complete Podman Desktop onboarding
In Podman Desktop:
- Select Start Onboarding.
- Allow Podman Desktop to install the Podman engine.
- Keep WSL 2 selected as the machine provider.
- Create the Podman machine when prompted.
- Install the Compose CLI when prompted.
- Complete onboarding and open the dashboard.
If onboarding was previously skipped:
- Open Settings > Resources.
- In the Podman tile, select Setup Podman.
- Create and start a WSL-based Podman machine.
- 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:
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
-
Download LM Studio for Windows from lmstudio.ai/download.
-
Run the installer and start LM Studio.
-
Complete the initial setup.
-
Open My Models in LM Studio.
-
Use the model-directory control to change the models directory to:
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:
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:
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:
D:\ai\mcp\WebAccess.MCP\deploy\compose.yml
Avoid an accidental double folder such as:
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:
winget install --exact --id Git.Git
Close and reopen PowerShell after Git installation, then run:
$AiRoot = "D:\ai"
Set-Location (Join-Path $AiRoot "mcp")
git clone <repository-url> WebAccess.MCP
Replace <repository-url> with the trusted URL supplied by the project owner.
Verify the repository
$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:
$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:
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:
.\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:
podman compose --project-name webaccess-mcp ps
Expected result:
postgresis running and healthy.searxngis running and healthy.webaccessis 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:
podman compose --project-name webaccess-mcp logs --tail 200
8. Verify the Running Services
Verify both local ports:
Test-NetConnection 127.0.0.1 -Port 28080
Test-NetConnection 127.0.0.1 -Port 28081
Both results should include:
TcpTestSucceeded : True
Verify the dedicated SearXNG instance:
(Invoke-RestMethod "http://127.0.0.1:28080/config").instance_name
The expected name is:
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:
-
Open Discover (
Ctrl+2). -
Search for a tool-capable instruct model appropriate for the computer.
-
Select a GGUF quantization. A 4-bit option is a practical starting point for many computers; larger quantizations need more RAM or VRAM.
-
Download the model.
-
Confirm in My Models that it was stored beneath:
D:\ai\llm\models -
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.
- Keep the Podman stack running.
- In LM Studio, open the Program tab in the right sidebar.
- Select Install > Edit mcp.json.
- If the file is empty, enter:
{
"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:
"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
commandorargs. - Do not add authentication headers.
- Do not use
http://127.0.0.1:28080; that is SearXNG, not MCP. - Do not use
localhostif local security software resolves it unexpectedly; use the exact127.0.0.1URL shown above.
- Save
mcp.json. - Confirm that
webaccessappears and is enabled in the Program tab. - Start or return to a chat with the tool-capable model loaded.
- 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_searchto 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
- Start Podman Desktop.
- Make sure the Podman machine is running.
- Open PowerShell and run:
Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp up --detach
- Start LM Studio.
- Load the desired tool-capable model.
- Confirm that
webaccessis enabled in the Program tab.
Stop a normal session
Close LM Studio if desired, then run:
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
Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp start
Remove containers but preserve data
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:
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:
Set-Location "D:\ai\mcp\WebAccess.MCP"
git pull
Do not overwrite or delete deploy\.env.
Rebuild and start:
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:
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:
podman info
If the machine cannot start, verify WSL 2:
wsl --status
LM Studio cannot connect to WebAccess.MCP
-
Confirm LM Studio is version 0.3.17 or later.
-
Confirm the URL is exactly
http://127.0.0.1:28081/mcp. -
Confirm
webaccessis enabled in LM Studio's Program tab. -
Run:
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 -
Check that
mcp.jsonis valid JSON.
A host port is already in use
Identify the owning process:
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:
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
- Open
http://127.0.0.1:28080/config. - Inspect the
searxngandwebaccesslogs in Podman Desktop. - 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.