MCP Server Setup Guide (Windows) — Leave Management Example

This README documents the full process of building a local MCP (Model Context Protocol) server in Python with uv, testing it with MCP Inspector, and connecting it to Claude Desktop on Windows — including the gotchas that come up along the way.

1. Project Setup

cd Desktop\MCP
mkdir my-mcp-server
cd my-mcp-server
uv init .
uv add "mcp[cli]"

Gotcha: Installing mcp[cli] with plain pip install mcp[cli] puts it in your global Python site-packages — NOT in the project's own uv virtual environment. uv run only sees packages installed via uv add (or uv pip install) inside the project. If you see:

Error: typer is required. Install with 'pip install mcp[cli]'

even after installing it, this is almost always the cause. Fix: run uv add "mcp[cli]" from inside the project folder.

2. Example main.py

Build your server using FastMCP from the mcp package: create an mcp = FastMCP("YourServerName") instance, define functions decorated with @mcp.tool() for actions the AI can call (each with a clear docstring describing what it does — Claude uses this to decide when to call it), and optionally @mcp.resource("scheme://{param}") for read-only data resources. End the file with:

if __name__ == "__main__":
    mcp.run()

For this walkthrough, the example server was a simple in-memory "LeaveManager" with three tools (get_leave_balance, apply_leave, get_leave_history) and one resource (greeting://{name}).

stdout is reserved for the JSON-RPC protocol — any stray print() corrupts the stream and causes cryptic JSON parse errors downstream. Use logging configured to stderr if you need debug output.

3. Test with MCP Inspector (recommended before touching Claude Desktop)

MCP Inspector is a browser-based tool for calling your tools directly — no AI, no Claude Desktop needed. Great for confirming your server actually works before wiring it into anything else.

uv run mcp dev main.py

This opens a local page (usually http://localhost:6274). Click Connect, then go to the Tools tab → List Tools → pick a tool → fill params → run it and check the output.

If Connect spams SyntaxError: Unexpected token ... is not valid JSON in the History/Notifications panel, it usually means the underlying command errored out in plain text (e.g. the same "typer is required" issue above) instead of returning JSON. Read the actual error text hiding in the syntax error message — it tells you what broke.

4. Connecting to Claude Desktop

4a. If Claude Desktop isn't installed yet

Download from https://claude.ai/download, install, and launch it at least once (finish sign-in) before doing anything else.

4b. Finding the right config file

This is the step that varies the most and caused the most confusion:

• Standard installs usually use: %APPDATA%\Claude\claude_desktop_config.json (i.e. C:\Users\<you>\AppData\Roaming\Claude\claude_desktop_config.json)

• Packaged/Store (MSIX) installs — recognizable by a path containing AppData\Local\Packages\Claude_<random-id>\... — use a virtualized config location instead, e.g.: ...\Local\Packages\Claude_<id>\LocalCache\Roaming\Claude\claude_desktop_config.json Windows silently redirects the app's "AppData\Roaming\Claude" reads/writes to this Packages folder, so editing the plain %APPDATA%\Claude copy does nothing for this install type.

• Easiest way to find the right one: open Claude Desktop → Settings → Developer (under "Desktop app" section) → Local MCP servers → click Edit Config. This always opens the file the app actually reads, regardless of install type.

Dead end to avoid: Settings → Connectors → Add custom connector looks like the obvious place to add a server, but it's only for remote MCP servers (ones reachable by a URL, e.g. a hosted server on the internet). It has no field for a local command like uv run main.py, so don't waste time there for a local stdio server — go to Developer → Local MCP servers instead.

4c. The config format

The file may already contain other keys (preferences, Cowork settings, etc. on newer builds). Just add mcpServers as a new top-level key — don't delete anything else:

{
  "mcpServers": {
    "leave-manager": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\<you>\\Desktop\\MCP\\my-mcp-server",
        "run",
        "main.py"
      ]
    }
  }
}

If "command": "uv" isn't found (Claude Desktop doesn't always inherit your terminal's PATH), use the full path instead, e.g.: C:\\Users\\<you>\\AppData\\Local\\Programs\\Python\\Python314\\Scripts\\uv.exe

4d. Restart and verify

1. Save the config file.
2. Fully quit Claude Desktop — right-click its icon in the system tray (bottom-right, near the clock) → Quit/Exit. Closing the window alone is not enough.
3. Reopen Claude Desktop.
4. Go to Settings → Developer → Local MCP servers — your server should show up with a green "running" badge.
5. Start a new chat and ask a natural question, e.g.: "How many leave days does E001 have left?" Claude should say "Loaded tools, used <your-server-name> integration" and answer using your tool's actual return value.

5. Quick troubleshooting checklist

Symptom	Likely cause	Fix
Error: typer is required...	mcp[cli] installed globally, not in project venv	uv add "mcp[cli]" inside the project folder
Claude app not found from mcp install	Claude Desktop not installed, or mcp install's auto-detect is unreliable	Install the app, or skip mcp install and edit the config file directly
Inspector shows repeated JSON parse errors	Server process is printing plain text instead of JSON (crash message, or a stray print())	Check the error text embedded in the parse error; fix the underlying issue
Settings → Developer → "No servers added" after editing config	Edited the wrong config file, or mcpServers key missing/malformed	Use Settings → Developer → Edit Config to find the actual file in use; verify JSON is valid
Server shows up but Claude never calls it	Ambiguous tool descriptions, or server crashed silently	Check "View Logs" next to the server entry in Settings → Developer

6. Useful commands reference

uv init .                      # create a new uv project
uv add "mcp[cli]"              # add MCP with CLI/dev tools as a dependency
uv run mcp dev main.py          # launch MCP Inspector against your server
uv run mcp install main.py      # (optional) attempt auto-install into Claude Desktop
uv run main.py                  # run the server standalone (useful for checking for crashes)