modelcontextprotocol / modelcontextprotocol/python-sdk

pywin32 installation fails on Windows — hard dep only needed for client stdio, but pulled in for all users via eager import in __init__.py

Open
#2,233 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement needs decision P2
Dominant language
Python
Stars
24.3k
Forks
4k
Avg merge
1d 1h
Merged PRs (30d)
31

Description

Initial Checks

Description

pywin32>=311 is a required Windows dependency used exclusively in mcp.client.stdio (Windows Job Objects for child process cleanup). However, mcp/__init__.py eagerly imports from .client.stdio import StdioServerParameters, stdio_client, which causes mcp/os/win32/utilities.py to unconditionally execute:

if sys.platform == "win32":
    import pywintypes
    import win32api
    import win32con
    import win32job

This means pywin32 is a hard runtime requirement on Windows for all users — including those running a pure MCP server that never uses mcp.client.stdio.

The pywin32 wheel contains a .data directory with Windows DLLs. On Windows, AV software (e.g. Windows Defender) locks newly-extracted DLLs before uv can clean up its temp directory, causing installation to fail every time with:

error: Failed to install: pywin32-311-cp313-cp313-win_amd64.whl (pywin32==311)
  Caused by: failed to remove directory `...\uv\cache\builds-v0\.tmp\Lib\site-packages\pywin32-311.data`
  os error 32 (file in use by another process)

This blocks server-only deployments like ha-mcp entirely on Windows (tracked in homeassistant-ai/ha-mcp#672).

The null-checks already in _create_job_object() and _maybe_assign_process_to_job() handle win32job = None gracefully — so the only missing piece is allowing the import to fail softly:

if sys.platform == "win32":
    try:
        import pywintypes, win32api, win32con, win32job
    except ImportError:
        win32api = win32con = win32job = pywintypes = None

Or alternatively, lazily import mcp.client.stdio from mcp/__init__.py so server-only users don't trigger this code path at all.

Example Code

# This alone triggers the pywin32 import on Windows:
from mcp.server.stdio import stdio_server

Python & MCP Python SDK

Python 3.13, MCP Python SDK 1.26.0 (latest)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with mcp/init.py and trace its eager import into mcp/client/stdio and mcp/os/win32/utilities.py. Check how the existing null-checks handle missing pywin32, then verify that importing mcp.server.stdio on Windows no longer requires pywin32 for server-only users while client stdio cleanup remains supported.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.