Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
The quickest Windows setup is a local Python server: install Python 3.10 or newer, install the Model Context Protocol SDK, create a small server file, and run uv run mcp dev server.py. That command starts the development server and MCP Inspector so you can call tools before connecting a host. Docker Desktop’s MCP Toolkit is the better choice when you need repeatable isolation, while Claude Desktop and Microsoft’s Windows on-device agent registry provide host and enterprise integration.
This guide shows all four routes, the Windows-specific paths and environment settings that commonly break, and a complete test server you can run locally.
Choose the Windows setup that matches your goal
| Route | Best for | Isolation and repeatability | Primary host or test tool |
|---|---|---|---|
| Local Python SDK | Learning, prototyping, or one machine | A local process; you manage its Python environment | MCP Inspector, then any MCP client |
| Docker MCP Toolkit | Catalogued servers and repeatable containers | Container isolation and reusable Toolkit profiles | Connected AI clients through the Docker gateway |
| Claude Desktop host | Using your own server inside Claude Desktop | Depends on the server process and Claude’s launch configuration | Claude Desktop |
| Windows on-device agent registry | Managed or enterprise deployment | Contained agent sessions with approved-resource restrictions when registered through the supported path | Windows on-device agent |
For a first experiment, start with the Python path. You can later install the same server into Claude Desktop or package it for Docker.
Path A: Build and test a local Python MCP server
1. Install the Windows prerequisites
- Install Python 3.10 or newer. The official Python SDK requires 3.10+.
- Install
uvor use an existing Python and pip installation. The SDK and CLI can be installed withuv add "mcp[cli]"orpip install "mcp[cli]". - Install Node.js if you want MCP Inspector. Inspector is a Node.js application and its launcher uses
npx.
Open a new PowerShell window after installation and verify the tools:
#1 Best Overall
python --version
uv --version
node --version
npx --versionIf you chose pip instead of uv, check pip --version as well. A new terminal matters because Windows applications launched by a host may receive a different, minimal PATH than your interactive shell.
2. Create a project and install the SDK
In PowerShell, create a directory and add the MCP package:
mkdir windows-mcp-demo
cd windows-mcp-demo
uv init
uv add "mcp[cli]"The equivalent pip installation is:
python -m venv .venv
..venvScriptsActivate.ps1
python -m pip install "mcp[cli]"If PowerShell blocks activation because of its execution policy, do not weaken system policy just for this test; invoke the environment’s interpreter directly, for example ..venvScriptspython.exe -m pip install "mcp[cli]".
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
3. Create server.py
This small server exposes one deterministic tool. It is intentionally self-contained, so you can verify the protocol before adding API calls, files, or databases.
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("Windows Demo")
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two integers."""
return a + b
if __name__ == "__main__":
mcp.run()Keep standard-output discipline in mind: an MCP stdio host expects protocol messages on stdout. Send diagnostic logging to stderr instead of printing debug text to stdout.
4. Launch MCP Inspector
From the project directory, run:
uv run mcp dev server.pyThe CLI starts the development server and opens MCP Inspector. In Inspector, connect to the generated server, list the available tools, call add with two integers, and confirm the returned sum. This is a development check; the command does not certify that a server is production-ready.
If uv is not recognized, locate it with where.exe uv and use that absolute path in your host configuration. Do the same for npx when Inspector cannot start. For example, a host command may need the full path to npx.cmd rather than simply npx.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →5. Add real tools safely
Expand one capability at a time and test it in Inspector. Validate arguments, return structured results where practical, and give the process only the files, network destinations, and credentials it needs. Never hard-code tokens in server.py; pass them as environment variables when the host launches the process.
Run the Python server in Claude Desktop
Use the SDK installer
The SDK CLI can generate a Claude Desktop launch entry:
uv run mcp install server.pyIt reads the server name, converts the script path to an absolute path, and writes the entry to %APPDATA%Claudeclaude_desktop_config.json. Fully quit and reopen Claude Desktop after installing or editing the configuration; closing only the chat window may leave the old process running.
Pass secrets explicitly
Claude Desktop does not automatically inherit the environment from the PowerShell window where you tested the server. Supply variables during installation with -v NAME=value, or load them from a dotenv file with -f .env. Keep the dotenv file out of source control and restrict its permissions.
Free tools Windows power users keep installed
One-click scans. No signup required.
uv run mcp install server.py -v WEATHER_API_KEY=replace-me
uv run mcp install server.py -f .envAfter relaunching Claude Desktop, ask it to list the tools exposed by the server and call the harmless add tool. If it worked in Inspector but not in Claude, compare the absolute interpreter/script path and the explicitly supplied environment variables first.
Path B: Docker Desktop MCP Toolkit
Enable the Toolkit
- Install Docker Desktop for Windows.
- Open Settings → Beta features and enable MCP Toolkit.
- Create a Toolkit profile, add servers from the catalog, connect an AI client, and verify the connection by invoking a tool.
The Toolkit is useful when several machines need the same catalogued configuration or when you prefer containers over installing every server dependency on Windows.
Use the Windows gateway configuration
Docker’s Windows example uses a full executable path such as C:/Program Files/Docker/Docker/resources/bin/docker.exe. It also passes the PROGRAMFILES and PROGRAMDATA environment variables. Set startup_timeout_sec = 60: Docker documents a default timeout of 10 seconds, while the gateway typically needs approximately 15–25 seconds to initialize.
docker.exe mcp gateway runThe exact client configuration varies by client, so copy the command and path shown by your Docker Desktop installation rather than assuming that docker is on the host’s PATH. In Docker’s example, verification is performed from a connected Vibe CLI by using /mcp to list servers and then issuing a GitHub pull-request prompt.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesPath C: Register servers with the Windows on-device agent
Know the registration families
Microsoft documents three Windows registration families:
- Package-identity apps, normally delivered through MSIX or external-location packaging.
- Directly installed MCP bundles.
- Manual registration of local or remote servers with the Windows on-device agent registry (ODR).
Servers accessed through the ODR run in a contained agent session with restrictions on approved resources. Microsoft describes this containment as a way to limit risks such as cross-prompt injection attacks.
Choose the enterprise-safe route
Use package identity or managed registration when distributing to an organization. A directly installed bundle without package identity cannot use the securely contained agent process unless the user explicitly enables the setting that reduces protections for agent connectors. That trade-off should be approved by an administrator, not enabled casually to make a tool appear.
Review every tool and resource before registration, narrow permissions to the minimum required, and keep credentials outside source files. Containment reduces exposure; it is not a universal security certification.
Windows troubleshooting
“uv” or “npx” is not found
GUI hosts often start with a minimal PATH. Run where.exe uv or where.exe npx, then place the returned absolute executable path in the host configuration. On Windows, the Node launcher may be named npx.cmd.
The server works manually but not in a host
The host may not inherit your interactive shell’s variables, current directory, or virtual-environment activation. Use absolute paths, install dependencies into the environment that the host launches, and pass required secrets with Claude’s -v or -f .env options.
Docker reports a gateway timeout
Replace a bare docker command with Docker Desktop’s full Windows path, pass PROGRAMFILES and PROGRAMDATA, and allow a 60-second startup timeout. The documented 10-second default can expire before the gateway finishes its normal 15–25-second initialization.
No tools appear in the Windows agent
Check the registration method first: package identity, bundle, or ODR. Confirm that the server meets the containment requirements. If it is a direct bundle, verify whether protections were reduced for agent connectors; without the required setting, the bundle may not run in the contained agent process.
Inspector or the host shows garbled protocol output
Remove every diagnostic print() from stdout. MCP stdio protocol traffic must remain on stdout; write logs to stderr instead. Restart the host after changing the script so it does not retain an old process.
Operational checklist before you share a server
- Run every tool at least once in Inspector and test invalid as well as valid arguments.
- Confirm the host uses an absolute script and interpreter path.
- List all environment variables and remove secrets from source and configuration committed to Git.
- Limit file, network, and command access to what each tool needs.
- For Docker, verify the profile, catalog server, client connection, and 60-second gateway timeout.
- For enterprise deployment, document the registration family and whether Windows containment is active.
- Keep protocol output clean and send diagnostics to stderr.
Or skip the browser setup
If the MCP task you need is taking clean website screenshots for an agent or workflow, ScreenshotNeo provides a website screenshot API and MCP server. It accepts one GET request and returns PNG, JPEG, WebP, or PDF. Before capture it accepts consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in X-Page-Verdict and X-Billed headers. Its MCP tools are take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
See the ScreenshotNeo API documentation for all options, including full-page and selector captures, dark mode, device presets, retina scale, PDF paper and page-range controls, custom CSS and JavaScript, clicks, waits, request blocking, headers, cookies, authorization, timezone, geolocation, transparent backgrounds, resizing, TTL caching, signed image links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting, and the OpenAPI specification.
One-call examples
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);There is a free allowance of 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is on every plan. Create a free ScreenshotNeo account to get an access key.
Frequently Asked Questions
Does MCP Inspector prove that a server is production-ready?
No. Inspector confirms that the development process starts and that calls return the expected values. Production readiness still requires permission review, secret handling, input validation, failure handling, and host-specific testing.
Why should a Windows host use absolute paths?
A desktop host can start with a different working directory and a smaller PATH than PowerShell. Absolute paths remove that ambiguity for the interpreter, script, and helper executables.
Can I move from the Python process to Docker later?
Yes. Keep the tool contract and environment variables documented, then package the server and select it through a Docker MCP Toolkit profile. Re-test each tool because container file and network permissions differ from a local process.
The Bottom Line
Use the local Python SDK and uv run mcp dev server.py to learn and test on Windows, Claude Desktop to make that server available in a desktop host, Docker MCP Toolkit for repeatable containers, and Windows ODR or package identity for managed enterprise registration. Explicit paths, explicit environment variables, clean stdio output, and a deliberate permission review prevent most setup failures.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchQuick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
