【Bug已解决】Trying to connect Claude desktop MCP to Home Assistant - Error pywin32-311.data locked 解决方案一、现象长什么样你在 Windows 上把 Home Assistant 的 MCP server 接进 Claude Desktop安装/启动阶段报Error: pywin32-311.data locked或pywin32-311.data is locked by another process多发生在pip install/uv拉起 Home Assistant 依赖、或 Claude Desktop 自动安装 MCP 包时报错指向pywin32这个 Windows 专用的 Python 包它装了 COM/Win32 扩展带.data目录有时是第一次能装上、重启 Claude Desktop 后再装就锁杀掉所有 Python / Claude 进程后有时能好但下次又复发表现和文件被占用一模一样——其实是 Windows 下pywin32的特殊安装机制 杀毒/索引器占用文件导致的。一句话在 Windows 上安装 Home Assistant MCP 依赖时pywin32的.data目录被其他进程杀毒、索引、或残留的 Python 进程锁定导致写入失败。二、背景pywin32是 Windows 平台访问 Win32 API 的 Python 扩展。它安装时除了放.pyd/.dll还会在一个.data子目录里写一些需要在安装后post-install注册到系统里的文件。这个目录在 Windows 上特别容易被文件锁盯上杀毒软件实时扫描边写边扫锁住.dataWindows Search / 索引器对新建文件加锁残留 Python 进程上一个没退干净的python.exe仍持有句柄Claude Desktop 自带的运行时它拉起 MCP 包时用了一个 Python 环境如果环境彼此干扰也会抢锁。Home Assistant 的 MCP 依赖树里会间接依赖pywin32因为 HA 生态里不少包依赖它做 Windows 服务/事件于是 CLAUDE MCP 接入 HA 时撞上了这个 Windows 专属坑。三、根因根因是Windows 文件锁 pywin32后安装写入.data的时序冲突pip/uv 解包 pywin32 wheel - 写 .data 目录post-install 注册 - Windows 杀毒/索引器对已写文件加锁 - pip 想把 .data 改名/移动 - 文件被锁 - pywin32-311.data locked这不是代码逻辑错而是Windows 平台的安装时序/文件锁问题。任何在 Windows 上装pywin32的场景都可能遇到只是 HA MCP 这条链路把它暴露出来了。四、最小可运行复现下面用 Python 模拟文件被占用导致写入失败还原锁的本质import os from pathlib import Path def write_data_dir(path: Path, holder_open: bool): path.mkdir(parentsTrue, exist_okTrue) target path / .data / registry.bin target.parent.mkdir(exist_okTrue) if holder_open: # 模拟杀毒/索引器/残留进程持有文件句柄 with open(target, wb) as lock: lock.write(bx) try: # 另一个写入者尝试覆盖 - Windows 上会 PermissionError/locked with open(target, wb) as w: w.write(by) except PermissionError as e: raise RuntimeError(f{path.name}.data locked: {e}) def main(): d Path(./demo_pywin32) try: write_data_dir(d, holder_openTrue) except RuntimeError as e: print(ERR:, e) if __name__ __main__: main()运行后文件被占用时抛 .data locked与真实现象同构。五、解决方案第一层最小直接修复最小修复是释放占用并干净重装 pywin32# 1. 彻底退出 Claude Desktop 与所有 python 进程任务管理器确认 # 2. 临时关闭杀毒实时扫描或把项目目录加入白名单 # 3. 强制重装 pywin32 pip install --force-reinstall --no-cache-dir pywin32 # 若用 uv uv pip install --reinstall pywin32 # 4. 重装完再拉起 Home Assistant MCP如果.data目录仍锁死手动删除残留再装# 以管理员身份运行 Remove-Item -Recurse -Force $env:LOCALAPPDATA\pip\cache -ErrorAction SilentlyContinue pip install --force-reinstall pywin32六、解决方案第二层结构化改进把Windows 下 pywin32 安装做成有护栏的策略避免锁冲突反复发生from dataclasses import dataclass import os import shutil import subprocess from pathlib import Path from typing import List dataclass(frozenTrue) class ClaudeMcpPywin32Policy: Windows pywin32 安装策略规避 .data 锁冲突。 规则 - 安装前尽量释放锁提示关闭占用进程/杀毒白名单 - 用 --force-reinstall --no-cache-dir 避免缓存里的坏 .data - 失败时给出明确的手动清理步骤 cache_dir: Path Path(os.path.expandvars(%LOCALAPPDATA%/pip/cache)) def release_locks_hint(self) - List[str]: return [ 关闭 Claude Desktop 与所有 python.exe 进程, 将项目目录加入杀毒软件实时扫描白名单, 以管理员身份运行终端, ] def clean_cache(self) - None: if self.cache_dir.exists(): shutil.rmtree(self.cache_dir, ignore_errorsTrue) def install(self) - int: self.clean_cache() return subprocess.call( [pip, install, --force-reinstall, --no-cache-dir, pywin32] ) def demo() - None: policy ClaudeMcpPywin32Policy() for h in policy.release_locks_hint(): print(-, h) # policy.install() if __name__ __main__: demo()七、解决方案第三层断言 / CI 守护import pytest from your_module import ClaudeMcpPywin32Policy def test_hints_non_empty(): policy ClaudeMcpPywin32Policy() assert len(policy.release_locks_hint()) 3 def test_install_command_shape(monkeypatch): policy ClaudeMcpPywin32Policy() captured {} def fake_call(cmd): captured[cmd] cmd return 0 monkeypatch.setattr(subprocess.call, fake_call) monkeypatch.setattr(shutil.rmtree, lambda *a, **k: None) assert policy.install() 0 assert --force-reinstall in captured[cmd] assert --no-cache-dir in captured[cmd] def test_cache_clean_runs(): import tempfile from pathlib import Path import shutil tmp Path(tempfile.mkdtemp()) / cache tmp.mkdir(parentsTrue) policy ClaudeMcpPywin32Policy(cache_dirtmp) policy.clean_cache() assert not tmp.exists()CI 在 Windows runner 上跑这条安装策略确保 HA MCP 依赖在 Windows 可复现安装。八、排查清单是否所有 Claude Desktop / python 进程都已退出任务管理器确认。杀毒实时扫描是否锁了.data把项目目录加白名单。是否用--force-reinstall --no-cache-dir重装 pywin32是否以管理员身份运行终端Windows 写系统目录需要权限。是否手动删过残留缓存再装是否换用 WSL / Linux 环境绕开 Windows 文件锁备选方案九、小结在 Windows 上把 Home Assistant MCP 接进 Claude Desktop 时遇到pywin32-311.data locked根因不是逻辑错误而是 Windows 文件锁与pywin32安装后写.data的时序冲突——杀毒/索引器或残留进程占住了文件。最小修复是退出占用进程、加白名单、以管理员身份--force-reinstall重装结构化做法是抽成ClaudeMcpPywin32Policy在安装前释放锁并清理缓存最后用 pytest 守护安装命令形态确保 Windows 上 HA MCP 依赖可稳定安装。
