Skip to content

fix(mcp): force UTF-8 encoding for Python stdio servers on Windows #909

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bj456736 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix(mcp): force UTF-8 encoding for Python stdio servers on Windows #909

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions packages/agent-core/src/mcp/client-stdio.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -236,5 +236,18 @@ export function mergeStdioEnv(
if (configEnv !== undefined) Object.assign(merged, configEnv);
Object.assign(merged, proxyEnvForChild(merged));
reconcileChildNoProxy(merged, configEnv);
// Ensure Python MCP servers use UTF-8 for stdio encoding.
// On Windows the default console code page (e.g. cp1252) cannot encode
// non-ASCII characters, causing UnicodeEncodeError when Python servers
// print Unicode to stdout/stderr. JSON-RPC over stdio is always UTF-8,
// so forcing the encoding is correct on every platform.
// See https://github.com/MoonshotAI/kimi-code/issues/886
if (merged['PYTHONIOENCODING'] === undefined) {
merged['PYTHONIOENCODING'] = 'utf-8';
}
if (merged['PYTHONUTF8'] === undefined) {
merged['PYTHONUTF8'] = '1';
Comment on lines +248 to +249

@chatgpt-codex-connector chatgpt-codex-connector Bot Jun 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Avoid forcing Python UTF-8 mode globally

For Windows Python MCP servers that read locale-encoded files with the default text encoding, this sets process-wide UTF-8 mode and changes behavior outside stdio; for example a server that previously read cp1252 user files via open(path) can now fail with a decode error. The stdio UnicodeEncodeError described here is already addressed by PYTHONIOENCODING=utf-8, so defaulting PYTHONUTF8=1 creates a broader compatibility regression unless the user knows to override it per server.

Useful? React with 👍 / 👎.

}

return merged;
}
21 changes: 21 additions & 0 deletions packages/agent-core/test/mcp/client-stdio.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -266,4 +266,25 @@ describe('mergeStdioEnv', () => {
const merged = mergeStdioEnv({ FOO: 'override' }, { FOO: 'parent', PATH: '/x' });
expect(merged['FOO']).toBe('override');
});

it('injects PYTHONIOENCODING=utf-8 and PYTHONUTF8=1 for Python MCP servers', () => {
const merged = mergeStdioEnv(undefined, { PATH: '/usr/bin' });
expect(merged['PYTHONIOENCODING']).toBe('utf-8');
expect(merged['PYTHONUTF8']).toBe('1');
expect(merged['PATH']).toBe('/usr/bin');
});

it('does not override user-provided PYTHONIOENCODING or PYTHONUTF8', () => {
const merged = mergeStdioEnv(
{ PYTHONIOENCODING: 'latin-1', PYTHONUTF8: '0' },
{ PATH: '/usr/bin' },
);
expect(merged['PYTHONIOENCODING']).toBe('latin-1');
expect(merged['PYTHONUTF8']).toBe('0');
});

it('inherits parent PYTHONIOENCODING when present', () => {
const merged = mergeStdioEnv(undefined, { PATH: '/usr/bin', PYTHONIOENCODING: 'cp1252' });
expect(merged['PYTHONIOENCODING']).toBe('cp1252');
});
});
Loading