659 lines
18 KiB
Markdown
659 lines
18 KiB
Markdown
# 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
|
|
<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:
|
|
|
|
```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 `<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 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 <repository-url> WebAccess.MCP
|
|
```
|
|
|
|
Replace `<repository-url>` 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.
|