fix: pipe stderr asynchronously to support Jupyter notebook environments

In Jupyter notebook environments, sys.stderr cannot reliably be used as
a subprocess file descriptor. This causes stdio_client to fail when
trying to start MCP servers from within Jupyter notebooks.

Changes:
- Always pipe stderr (subprocess.PIPE) instead of passing sys.stderr
  directly to the subprocess
- Add async stderr_reader task that reads stderr output and forwards it
  to the errlog stream (or ANSI-colored print output in Jupyter)
- Add _is_jupyter_notebook() helper to detect Jupyter environments via
  isinstance check against ZMQInteractiveShell
- Remove errlog parameter from _create_platform_compatible_process and
  create_windows_process since stderr is now always piped
- Update win32 utilities to always use subprocess.PIPE for stderr

Fixes #156

Author: michaelxer

src/mcp/client/stdio.py

@@ -1,5 +1,6 @@
 import logging
 import os
+import subprocess
 import sys
 from contextlib import asynccontextmanager
 from pathlib import Path
@@ -24,6 +25,22 @@
 
 logger = logging.getLogger(__name__)
 
+
+def _is_jupyter_notebook() -> bool:
+    """Check if running in a Jupyter notebook environment.
+
+    Returns True when running inside Jupyter Notebook, JupyterLab, or
+    any IPython kernel that uses ZMQ for communication.
+    """
+    try:
+        from ipykernel.zmqshell import ZMQInteractiveShell  # type: ignore
+        from IPython import get_ipython  # type: ignore
+
+        return isinstance(get_ipython(), ZMQInteractiveShell)  # type: ignore[no-untyped-def]
+    except Exception:
+        return False
+
+
 # Environment variables to inherit by default
 DEFAULT_INHERITED_ENV_VARS = (
     [
@@ -123,7 +140,6 @@ async def stdio_client(server: StdioServerParameters, errlog: TextIO = sys.stder
             command=command,
             args=server.args,
             env=({**get_default_environment(), **server.env} if server.env is not None else get_default_environment()),
-            errlog=errlog,
             cwd=server.cwd,
         )
     except OSError:
@@ -177,9 +193,32 @@ async def stdin_writer():
         except anyio.ClosedResourceError:  # pragma: no cover
             await anyio.lowlevel.checkpoint()
 
+    async def stderr_reader():
+        """Read stderr from the process and forward to errlog.
+
+        In Jupyter notebook environments, sys.stderr cannot reliably be used
+        as a subprocess file descriptor. By always piping stderr and reading
+        it asynchronously, we ensure output is visible in all environments:
+        Jupyter gets ANSI-colored print output; other environments write
+        directly to the errlog stream (defaulting to sys.stderr).
+        """
+        assert process.stderr, "Opened process is missing stderr"
+
+        in_jupyter = _is_jupyter_notebook()
+        try:
+            async for line in process.stderr:
+                text = line.decode(errors="replace").rstrip("\n")
+                if in_jupyter:
+                    print(f"\033[91m{text}\033[0m")
+                else:
+                    print(text, file=errlog)
+        except anyio.ClosedResourceError:  # pragma: lax no cover
+            await anyio.lowlevel.checkpoint()
+
     async with anyio.create_task_group() as tg, process:
         tg.start_soon(stdout_reader)
         tg.start_soon(stdin_writer)
+        tg.start_soon(stderr_reader)
         try:
             yield read_stream, write_stream
         finally:
@@ -230,21 +269,24 @@ async def _create_platform_compatible_process(
     command: str,
     args: list[str],
     env: dict[str, str] | None = None,
-    errlog: TextIO = sys.stderr,
     cwd: Path | str | None = None,
 ):
     """Creates a subprocess in a platform-compatible way.
 
     Unix: Creates process in a new session/process group for killpg support
     Windows: Creates process in a Job Object for reliable child termination
+
+    Stderr is always piped so that the caller can read it asynchronously.
+    This is required because sys.stderr may not be a valid subprocess file
+    descriptor in environments such as Jupyter notebooks.
     """
     if sys.platform == "win32":  # pragma: no cover
-        process = await create_windows_process(command, args, env, errlog, cwd)
+        process = await create_windows_process(command, args, env, cwd=cwd)
     else:  # pragma: lax no cover
         process = await anyio.open_process(
             [command, *args],
             env=env,
-            stderr=errlog,
+            stderr=subprocess.PIPE,
             cwd=cwd,
             start_new_session=True,
         )

src/mcp/os/win32/utilities.py

@@ -173,7 +173,7 @@ async def create_windows_process(
             creationflags=subprocess.CREATE_NO_WINDOW  # type: ignore
             if hasattr(subprocess, "CREATE_NO_WINDOW")
             else 0,
-            stderr=errlog,
+            stderr=subprocess.PIPE,
             cwd=cwd,
         )
     except NotImplementedError:
@@ -184,7 +184,7 @@ async def create_windows_process(
         process = await anyio.open_process(
             [command, *args],
             env=env,
-            stderr=errlog,
+            stderr=subprocess.PIPE,
             cwd=cwd,
         )
 
@@ -209,7 +209,7 @@ async def _create_windows_fallback_process(
             [command, *args],
             stdin=subprocess.PIPE,
             stdout=subprocess.PIPE,
-            stderr=errlog,
+            stderr=subprocess.PIPE,
             env=env,
             cwd=cwd,
             bufsize=0,  # Unbuffered output
@@ -221,7 +221,7 @@ async def _create_windows_fallback_process(
             [command, *args],
             stdin=subprocess.PIPE,
             stdout=subprocess.PIPE,
-            stderr=errlog,
+            stderr=subprocess.PIPE,
             env=env,
             cwd=cwd,
             bufsize=0,

tests/issues/test_1027_win_unreachable_cleanup.py

@@ -195,7 +195,7 @@ def echo(text: str) -> str:
         # This test manually manages the process to verify stdin-based shutdown
         # Start the server process
         process = await _create_platform_compatible_process(
-            command=sys.executable, args=[server_script], env=None, errlog=sys.stderr, cwd=None
+            command=sys.executable, args=[server_script], env=None, cwd=None
         )
 
         # Wait for server to start