Skip to content

fix: resolve Windows stdio JSON parsing errors and add Claude configuration docs#292

Merged
tirth8205 merged 1 commit into
tirth8205:mainfrom
Thamindu-Dev:fix/windows-fastmcp-stdio
Apr 18, 2026
Merged

fix: resolve Windows stdio JSON parsing errors and add Claude configuration docs#292
tirth8205 merged 1 commit into
tirth8205:mainfrom
Thamindu-Dev:fix/windows-fastmcp-stdio

Conversation

@Thamindu-Dev
Copy link
Copy Markdown
Contributor

Describe the pull request

This PR addresses a critical blocker for Windows users where the MCP server fails to connect to Claude Code, throwing Invalid JSON: EOF while parsing a value and Connection closed errors during the stdio stream initialization.

Root Causes & Fixes:

  1. FastMCP Stdio Bug: Older versions of fastmcp (locked at <3) fail to properly handle newline characters (\n) in Windows stdio streams. Bumped the fastmcp constraint to >=3.2.4 and regenerated the uv.lock file to pull the upstream fix.
  2. Configuration Docs: Added a dedicated section in the README.md for Windows users. Using the typical cmd /c wrapper in Claude's configuration injects unwanted terminal echoes into the stream, crashing the parser. Documented the direct .exe execution approach using "env": {"PYTHONUTF8": "1"} to ensure stable communication.

Testing:
Tested locally on Windows 11 with Claude Code CLI. The server now successfully connects and maintains the stream without parsing crashes.

…and add Windows setup guide for Claude Code MCP integration
@tirth8205
Copy link
Copy Markdown
Owner

Thanks for the Windows fix and docs! However, the fastmcp dependency change from >=2.14.0,<3 to >=3.2.4 is a major version bump that could break existing users. Could you keep the docs/README changes but either: (a) keep fastmcp on v2, or (b) ensure backward compatibility with the fastmcp v3 API in a separate PR with proper migration notes?

@tirth8205 tirth8205 merged commit 1abaac2 into tirth8205:main Apr 18, 2026
1 check passed
@Thamindu-Dev
Copy link
Copy Markdown
Contributor Author

Thanks for reviewing and merging the docs! I understand the concern about the major version bump. I'll take a look at option (b) and see if I can put together a separate PR to safely migrate the codebase to the fastmcp v3 API.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants