FreeCAD MCP 远程连接与安全完整指南：IP 白名单、认证 Token 与 SSH 隧道-迪斯科星球

FreeCAD MCP 远程连接与安全完整指南：IP 白名单、认证 Token 与 SSH 隧道

【免费下载链接】freecad-mcpFreeCAD MCP(Model Context Protocol) server项目地址: https://gitcode.com/gh_mirrors/fr/freecad-mcp

FreeCAD MCP 让 Claude Desktop 等 MCP 客户端直接控制 FreeCAD，完成建模、跑脚本、FEM 分析等操作。当你想让另一台电脑（MCP 客户端）控制远程 FreeCAD 时，就需要用到FreeCAD MCP 远程连接功能：通过 IP 白名单限制来源、用认证 Token 拦截未授权请求，或在不可信网络上用 SSH 隧道加密传输。本文带你从零配置，并讲清每一步背后的安全原理。

先了解 FreeCAD MCP 的两大组件 🔧

FreeCAD MCP 由两部分组成：

FreeCAD 插件：运行在 FreeCAD 内部的 RPC 服务器（默认监听localhost:9875，只接受本机连接）；
MCP Server：由 MCP 客户端（如 Claude Desktop）通过uvx freecad-mcp启动，负责与 AI 对话并转发命令。

下图演示了 AI 通过 FreeCAD MCP 自动设计法兰的完整过程：

默认配置下连接只走localhost，这是最安全但只能本机使用的模式。想跨机器控制时，请按下面步骤操作。

一步开启远程连接：配置 IP 白名单

⚠️ 重要：开启远程连接后，RPC 服务器不做任何流量加密，且默认没有任何认证。任何能访问到端口的程序都可以调用所有工具，包括execute_code（以你的用户权限在 FreeCAD 内运行任意 Python 代码）。因此远程连接必须配合认证 Token 使用。

在FreeCAD MCP菜单中操作（见 docs/configuration.md）：

勾选Remote Connections—— 服务器将绑定0.0.0.0（所有网卡），但只响应白名单内的地址；
点击Configure Allowed IPs，输入逗号分隔的 IP 或 CIDR 网段，例如192.168.1.100, 10.0.0.0/24。非法条目会被弹窗拒绝；
修改后重启 RPC 服务器生效。

先在视图菜单中切换到MCP Addon工作台，即可看到 FreeCAD MCP 工具栏：

白名单的解析与校验逻辑位于 addon/FreeCADMCP/rpc_server/ip_filter.py，所有设置保存在 addon/FreeCADMCP/rpc_server/settings.py 管理的freecad_mcp_settings.json中。

白名单请保持最小化：只加你真正要用的那台客户端机器的 IP，能用单个 IP 就不要放整个网段。

最快配置 MCP 客户端：`--host`参数

客户端配置只需加一个--host参数，指向运行 FreeCAD 的机器（该值会在启动时校验，必须是合法 IPv4/IPv6 地址或主机名）：

{ "mcpServers": { "freecad": { "command": "uvx", "args": ["freecad-mcp", "--host", "192.168.1.100"] } } }

修改配置后重启 MCP 客户端即可。--host的参数解析见 src/freecad_mcp/server.py。

💡 注意：无头脚本（headless execution）运行在MCP 服务器所在机器上，与--host无关，其文件路径必须在那台机器上可访问。

设置认证 Token：防止他人执行任意代码

IP 白名单只是"粗筛"，真正把关的是FreeCAD MCP 认证 Token：

在FreeCAD MCP菜单点击Set Auth Token，填入一个长随机值，可用这条命令生成：
```
python -c "import secrets; print(secrets.token_urlsafe(32))"
```
重启 RPC 服务器。此后服务器只响应携带正确 Token 的请求，未授权请求会被拒绝并记录在 FreeCAD 控制台。清空该字段即可关闭认证。

让 MCP 服务器携带同一个 Token，推荐用环境变量FREECAD_MCP_TOKEN：

{ "mcpServers": { "freecad": { "command": "uvx", "args": ["freecad-mcp", "--host", "192.168.1.100"], "env": { "FREECAD_MCP_TOKEN": "<FreeCAD 中设置的 Token>" } } } }

为什么推荐环境变量？命令行参数--auth-token也能工作，但同机其他用户可以在进程列表中看到命令行内容，Token 会泄露。

Token 校验采用常量时间比较（防时序攻击），同时兼容Bearer和 HTTP Basic 两种头格式，实现见 tests/test_auth.py 的测试用例与 addon/FreeCADMCP/rpc_server/ip_filter.py 中的authorization_ok函数。

🔒 由于 Token 明文传输，在你不控制的网络（如公司公共 Wi-Fi）上，请改用下面的 SSH 隧道方案。

更安全的替代方案：SSH 隧道

不开放端口、流量全程加密——在运行 MCP 服务器的机器上执行：

ssh -N -L 9875:localhost:9875 user@freecad-host

这样本地localhost:9875就直通远程机器的 RPC 端口，效果等同本机连接：

FreeCAD 端保持 Remote Connections 关闭（默认状态），服务器只响应发往localhost/127.0.0.1的请求；
MCP 客户端配置保持默认--host localhost，无需任何 Token；
安全边界完全交给 SSH 的密钥认证与加密来保证。

这是官方文档推荐的"不信任网络"首选方案。

启动验证与常见错误排查

配置完成后点击Start RPC Server，底部状态栏会出现启动信息：

✅ 成功：RPC Server started at 127.0.0.1:41757 (PID ...)，远程模式还会显示Allowed IPs与Auth token required字样：

❌ 失败示例：RPC Server failed to start: OSError: [errno 98] Address already in use——端口被占用，通常是之前的实例没停干净，先点Stop RPC Server再重试：

安全清单：配置完成前自查 ✅

检查项	建议
远程连接开着但没设 Token？	❌ 绝不允许，控制台也会打印警告
白名单范围	越窄越好，单 IP 优于网段
网络是否可信	不可信网络改用 SSH 隧道
Token 存放方式	用`FREECAD_MCP_TOKEN`环境变量，不用`--auth-token`
服务器还拒绝了什么？	所有来自网页浏览器的请求（防 CSRF/DNS 重绑定攻击）

值得一提：即使不设 Token，服务器也硬性拒绝任何网页发起的请求（带Origin头的 POST 一律 403），恶意网页无法调用它执行代码。

企业官网建设流程全解析