fm-mcp

fm-mcp

一个 MCP 服务，可让 Claude Code 和 Codex 等编码 Agent 将简单的文本任务交给 Apple Foundation Models 的设备端模型处理，也就是随 macOS 27 附带的 fm。它免费、私密，并且可离线运行。

mcp-name: io.github.yrangana/fm-mcp

网站： yrangana.github.io/fm-mcp，以及构建过程中的经验：设备端模型经实测的能力上限。

由 Yasiru Rangana 创建，他是悉尼的 AI 架构师和 AI 工程师。

为什么

编码 Agent 会为简单任务消耗付费的远程 Token，例如总结日志或从文档中提取字段。Mac 上已有的小型模型就能免费完成其中许多工作，而且文本不会离开设备。fm-mcp 让 Agent 可以交接这些任务，并明确告知它小型模型无法完成哪些工作。

安装

fm-mcp 目前为公开测试版（0.1.x）：可以正常使用且经过测试，但工具详情可能会在不同版本之间发生变化。CHANGELOG.md 列出了变更内容。

你需要一台搭载 Apple Silicon 的 Mac（不支持 Intel Mac）、开启了 Apple Intelligence 的 macOS 27，并且接受过一次 fm 许可协议（fm license）。这就是全部支持范围：fm-mcp doctor 会逐项检查，其他配置均不受支持。

还没有 Homebrew？请先从 brew.sh 安装。安装程序会询问是否安装 Xcode 命令行工具：接受并等待安装完成。

brew install yrangana/tap/fm-mcp
fm-mcp install    # sets up Claude Code and Codex
fm-mcp doctor     # checks everything fm-mcp needs

然后启动一个新的 Claude Code 或 Codex 会话。首次调用工具时，fm-mcp 会自行启动模型服务（fm serve），并在会话结束时将其停止。

获取二进制文件的其他方式：

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/yrangana/fm-mcp/releases/latest/download/fm-mcp-installer.sh | sh
cargo install fm-mcp

fm-mcp install 会修改什么

• **Claude Code：**将 fm-mcp MCP 服务添加到 ~/.claude.json（如果存在 claude 命令，则通过 claude mcp add 添加），并将 fm-delegate 技能安装到 ~/.claude/skills/。
• **Codex：**将 [mcp_servers.fm-mcp] 添加到 ~/.codex/config.toml，并在 ~/.codex/AGENTS.md 中添加带标记的部分（如果你使用 AGENTS.override.md，则添加到该文件中）。

它会在修改每个文件前备份，并打印所有受影响的路径；再次运行不会产生任何变化。--claude 或 --codex 用于选择一个 Agent，--dry-run 用于显示变更而不写入，--no-guidance 用于跳过技能和 AGENTS.md 部分。fm-mcp install --uninstall 会移除它添加的所有内容。

技能和 AGENTS.md 部分会告诉 Agent 何时交接任务。没有它们，Agent 只能看到工具说明，交接效果也会较差。

或者：Claude Code 插件

该插件无需运行 fm-mcp install，即可为 Claude Code 提供 MCP 服务和技能。但你仍需先将二进制文件安装到 PATH 中（参见上方的 Homebrew 安装说明）；否则 Claude Code 会报告服务连接失败。

/plugin marketplace add yrangana/fm-mcp
/plugin install fm-mcp@fm-mcp

Claude Code 应使用该插件或运行 fm-mcp install，不要同时使用：两者一起使用会让 Claude Code 启动两个 fm-mcp 服务。使用插件时，请运行 fm-mcp install --codex，仅配置 Codex。

其他 MCP 客户端

fm-mcp 是一个纯 stdio MCP 服务，因此其他能在同一台 Mac 上运行本地服务的客户端也可以使用它。fm-mcp install 不会为它们进行设置，而且它们也不会获得委派指导：Agent 只能根据工具描述自行判断。下方列出的客户端都在真实 Mac 上试用过；其他客户端可能也能使用，但未经测试。

Claude Desktop（使用 2.31226.1 试用，2026-10-11）。在 Settings › Developer › Edit Config 中，将以下内容添加到 mcpServers 的 claude_desktop_config.json 中，然后退出并重新打开 Claude Desktop：

"fm-mcp": {
  "command": "/opt/homebrew/bin/fm-mcp",
  "args": []
}

使用完整路径（which fm-mcp 会显示路径）。fm-mcp 最适合处理 Mac 上的文件：将文件路径提供给 Claude，它就会传入 path，因此文本不会经过 Claude。对于网页，Claude Desktop 会先自行读取页面，所以委派任务并无益处。

Devin（前身为 Windsurf）（使用 Devin.app 3.8.20 试用，2026-10-11）。将以下内容添加到 ~/.config/devin/mcp_config.json 中的 mcpServers：

"fm-mcp": {
  "type": "stdio",
  "command": "/opt/homebrew/bin/fm-mcp",
  "args": []
}

工具

工具	功能	可处理的数据量
summarise	将日志、文档、笔记和转录内容浓缩为概要：一段文字，或最多 7 条要点。并非完整记录。	约 30,000 个散文词，但对于内容密集的日志，仅约 1,000 行。长文本会被拆分后合并，这需要一两分钟，也可能丢失细节。
extract	根据你提供的 JSON Schema，从一段文本中提取指定字段并输出为 JSON。使用扁平 Schema 效果最佳。	约 3,500 个散文词。
classify	将一段文本归入你指定的标签（一项标签，或使用 multi 选择多个标签）。	约 3,500 个散文词。
ocr	读取 PNG、JPEG、HEIC、TIFF、GIF 或 BMP 图像中的文字。不支持 PDF。	一张图像。

summarise、extract 和 classify 接受 text，也可以接受文本文件的 path（最大 1 MB），这样 Agent 就不必亲自读取文件。docs/TOOLS.md 列出了所有参数，并附有调用示例。

限制

• 模型较小，上下文也较短： 约 8K 个 token，由输入和回答共享。充满 ID 和数字的日志，每个词消耗的 token 远多于散文。
• 不适用于代码、数学、推理、文本中没有的事实，或错误代价高且无法核查的情况。
• 它会出错。 摘要可能遗漏或歪曲细节。对于文本中不存在的字段，extract 经常会返回 null，但并不总是如此：在短发票中，缺少的采购订单编号在 25 次运行中有 10 次被供应商名称替代。模型在某个字段上卡住时，fm-mcp 会保留已完成的字段，将卡住的字段设为 null 并说明情况；这次调用约需 15 s。只询问文本中可能存在的字段。嵌套 Schema 的可靠性低于扁平 Schema。请核查重要内容。
• 一次只能处理一个请求。 Mac 上的所有会话共用同一个模型，因此调用会排队：短 extract 需要 1–2 s，长 summarise 则需要一分钟或更久。
• 安全过滤器： 设备端模型有时会拒绝无害的输入。fm-mcp 会明确报告这一点，并由 Agent 自行完成任务。

隐私

所有操作都在你的 Mac 上运行。fm-mcp 通过本地 Unix 套接字与 fm serve 通信，不会向网络发送任何内容。你的文本只会发送给设备端模型。SECURITY.md 介绍了详细信息，以及如何私下报告安全问题。

故障排除

运行 fm-mcp doctor。它会检查 Mac、macOS、fm、许可证、模型、测试请求以及两个 Agent 的设置，并说明如何修复发现的问题。

问题	修复方法
尚未同意许可证	运行一次 fm license。
模型不可用	在“系统设置”中启用 Apple Intelligence，并等待模型完成下载。
工具提示模型“卡住了”	通常是因为架构中包含文本未提及的字段，或者另一个会话正在使用该模型。尝试使用更扁平的架构。
工具处理长输入时超时	提高限制：在 MCP 服务的环境中设置 FM_MCP_REQUEST_TIMEOUT_SECS（默认值为 120）。
需要更多详细信息	在 MCP 服务的环境中设置 FM_MCP_LOG=debug。fm-mcp 只向 stderr 写入日志（stdout 用于传输 MCP 协议）。

卸载

fm-mcp install --uninstall
brew uninstall fm-mcp

开发

git clone https://github.com/yrangana/fm-mcp.git
cd fm-mcp
cargo build --release
./target/release/fm-mcp install    # points your agents at this build

cargo test --features fake-fm      # needs no Apple Intelligence: uses a fake fm
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --check
scripts/real_fm_smoke.sh           # checks against the real fm on this Mac

AGENTS.md 介绍了架构、关于 fm serve 的测试事实以及项目规则。docs/MANUAL_TEST.md 是每个版本的检查清单。

许可证

MIT。fm-mcp 与 Apple 无关联，也未获 Apple 背书。它会调用 Mac 上安装的 fm 工具，不包含任何 Apple 提供的内容。

由 Yasiru Rangana 创建。