fnos-mcp

将 fnos-skill 的 trim-cli 封装为 MCP 服务器（基于 FastMCP），让任何 MCP 客户端（Claude Desktop、Knot、Cursor 等）都能用自然语言管理飞牛 fnOS NAS。

功能覆盖

83 个 MCP 工具，覆盖 trim-cli 的完整能力面：

Related MCP server: feiniunas-mcp

安装

git clone https://github.com/Muwei-TA/fnos-mcp.git
cd fnos-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

要求 Python ≥ 3.10。vendor/trim-cli/ 已内置六平台二进制（Linux x64/arm64、macOS x64/arm64、Windows x64/arm64），开箱即用，无需单独安装 trim-cli。

配置 MCP 客户端

stdio 方式（推荐，适用于 Claude Desktop / Knot 等）：

{
  "mcpServers": {
    "fnos": {
      "command": "/path/to/fnos-mcp/.venv/bin/python",
      "args": ["-m", "fnos_mcp.server"]
    }
  }
}

HTTP 方式（先启动服务端 fnos-mcp --transport http --port 8000，客户端连 http://127.0.0.1:8000/mcp）。

首次登录（OAuth 2.0 + PKCE）

MCP 客户端中对话式完成：

1. 让客户端调用 login，参数给 host（如 fnos.muwei.xyz）和 port/scheme

2. 工具返回授权 URL，在浏览器打开、登录 fnOS 并确认授权

3. 把页面显示的一次性 code 告诉客户端，由 submit_auth_code 完成交换

也可以先在本机命令行手动登录（session 存在 ~/.config/trim-cli/，MCP 服务共用）：

vendor/trim-cli/trim-cli-linux-x64 --profile default --host <host> --port 443 --scheme https login

说明：

• 登录仅支持 OAuth 2.0 授权码 + PKCE，不处理账号密码

• 远程明文 HTTP 需 allow_insecure_http=True；自签 HTTPS 需 tls_insecure=True

• 会话 token 自动刷新；连续 401 时需重新登录

安全设计

• 写操作命令一律显式传 --yes，避免 CLI 交互确认卡死 MCP 进程

• 危险操作（power_reboot、file_trash_clear、docker_container_rm 等）在工具描述中明确标注，由客户端侧决定是否二次确认

• 不封装 media 命令（fnos-skill 明确排除 Media API）

• login 使用 15 秒超时提取授权 URL 后返回，不阻塞 MCP 进程

项目结构

fnos-mcp/
├── fnos_mcp/
│   ├── cli.py       # trim-cli 二进制引导与执行层
│   └── server.py    # FastMCP 服务器与 83 个工具定义
├── vendor/trim-cli/ # 六平台 trim-cli 二进制（来自 fnos-skill fa21571）
├── pyproject.toml
└── README.md

致谢

• fnos-skill 提供 trim-cli 与全部 fnOS API 能力

• FastMCP 提供 MCP 服务器框架

License

MIT