Ffl Mcp – Give Ai A "send File" Capability Via P2p (local First)

ffl-mcp（仅限本地）

ffl 的 MCP 服务。让 AI 帮你分享任何内容。

由 ffl 提供支持，可将任意文件/文件夹转换为 HTTPS 链接。

此 MCP 服务会在本地使用 ffl-python 绑定。 不会向 LLM 发送文件内容；模型只会触发本地 ffl。

此演示展示了协作调试：左侧的 Claude 通过 P2P 链接分享本地环境（DB + 日志），右侧的 Claude 下载并诊断错误。在此场景中，两个 Claude 代表在不同机器上工作的不同人员。

---

目录

• 安装
  • Windows — 图形界面安装程序
  • Linux / macOS — 一行命令
  • Windows — 一行命令（PowerShell）
  • uvx（无二进制文件，需要 uv）
  • Claude Code 云会话
  • 直接运行（开发）
• MCP 配置（手动 JSON）
• 工具
  • 分享
  • 从远程 Agent 分享
  • 下载
  • 生成密钥
  • 会话管理
• 说明
• 测试
• WSL2 用户

---

安装

⚡ 便捷短链接

• Linux/macOS： curl -fsSL https://fastfilelink.com/mcp/install.sh | bash
• Windows（脚本）： iwr -useb https://fastfilelink.com/mcp/install.ps1 | iex

🔒 fastfilelink.com/mcp/* 会重定向到 GitHub。如果你更喜欢直接访问 GitHub，请使用下方的直接链接。

Windows — 图形界面安装程序

从最新版本下载并运行 ffl-mcp-setup.exe。

它会将此服务注册到 Claude Desktop、Claude Code、Codex 和 Grok Build。

无需使用命令行 — 安装程序会自动将 ffl-mcp 注册到 Claude Desktop 和 Claude Code。

Linux / macOS — 一行命令

curl -fsSL https://raw.githubusercontent.com/nuwainfo/ffl-mcp/refs/heads/main/scripts/Install.sh | bash

从最新的 GitHub 版本下载对应平台的二进制文件，并运行 ffl-mcp install，将其注册到 Claude、Codex 和 Grok Build。如果你的平台没有可用的二进制文件，则会自动改用 uvx。

Windows — 一行命令（PowerShell）

iwr -useb https://raw.githubusercontent.com/nuwainfo/ffl-mcp/refs/heads/main/scripts/Install.ps1 | iex

从最新的 GitHub 版本下载 ffl-mcp.exe，并将其注册到 Claude、Codex 和 Grok Build。

uvx（无二进制文件，需要 uv）

uvx --from git+https://github.com/nuwainfo/ffl-mcp install

可通过 --target 控制目标（默认：全部）：

uvx --from git+https://github.com/nuwainfo/ffl-mcp install --target claude-desktop,claude-code,codex,grok-build

uvx --from git+https://github.com/nuwainfo/ffl-mcp install --print

claude-code 使用 Claude Code CLI。codex 会写入 Codex 客户端使用的原生 ~/.codex/config.toml 配置。grok-build 会写入 ~/.grok/config.toml，Grok Build 可从 /mcps 重新加载该配置。

旧版目标名称（claude-cli、codex-cli、codex-desktop 和 grok）仍可作为别名使用。安装程序会先为其更改的任何配置创建带时间戳的备份。

若要使用自定义配置路径，请传入文件：

uvx --from git+https://github.com/nuwainfo/ffl-mcp install --config /path/to/claude_desktop_config.json
uvx --from git+https://github.com/nuwainfo/ffl-mcp install --codex-config /path/to/codex/config.toml
uvx --from git+https://github.com/nuwainfo/ffl-mcp install --grok-config /path/to/grok/config.toml

Claude Code 云会话

托管在云端的 Claude Code 会话会在全新的容器中启动。若要让每个新会话都能使用 ffl-mcp， 请打开会话标题栏中的云环境菜单，选择 编辑，并将以下内容添加为环境的 设置脚本：

claude mcp add ffl -s user -e FFL_USE_STDIN=1 -- uvx --from git+https://github.com/nuwainfo/ffl-mcp ffl-mcp

设置脚本会在每个新会话启动时运行。在第一个新会话中， 运行 claude mcp list，确认 ffl 服务已注册。

直接运行（开发）

前置条件：已安装 uv。

# optional safety: restrict file sharing to a directory
export ALLOWED_BASE_DIR="$HOME/Downloads"

# optional: use stdin for text/base64 instead of temp files
export FFL_USE_STDIN=1

uvx --from git+https://github.com/nuwainfo/ffl-mcp ffl-mcp

MCP 配置（手动 JSON）

{
  "mcpServers": {
    "ffl": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/nuwainfo/ffl-mcp", "ffl-mcp"],
      "env": {
        "ALLOWED_BASE_DIR": "/Users/you/Downloads",
        "FFL_USE_STDIN": "1"
      }
    }
  }
}

---

工具

分享

工具	输入
fflShareText(text, name?, ...)	纯文本
fflShareBase64(dataB64, name?, ...)	二进制数据（Base64 编码）
fflShareFile(path, name?, ...)	单个本地文件或文件夹
fflShareFiles(paths, name?, ...)	多个文件（ffl 会自动将其打包为一个下载文件）
所有共享工具的通用选项：

选项	默认值	描述
e2ee	False	端到端加密
qrInTerminal	False	返回 ASCII 二维码图案（响应中的 qrCode）
authUser / authPassword	—	使用 HTTP Basic Auth 保护链接
maxDownloads	1	达到 N 次下载后停止提供服务（仅限 P2P）
timeoutSeconds	1800	无活动超时时间，单位为秒（仅限 P2P）
recipientAuth	—	pickup（6 位代码）、pubkey（RSA）、pubkey+pickup 或 email（OTP）
pickupCode	自动	为 pickup 模式指定的取件代码
recipientPublicKey	—	pubkey 模式下 .fflpub 文件的路径
recipientEmail	—	email OTP 模式下的邮箱，多个邮箱以逗号分隔
alias	—	自定义链接别名，例如 my-release（需要 Standard+ 账户）
receipt	—	收件人下载时发送邮件通知
receiptConfirm	—	下载前要求收件人确认；传入一条消息或 ""
forceRelay	False	禁用 WebRTC，通过隧道转发所有流量
transport	—	显式选择 p2p 或 relay。p2p 会覆盖自动检测到的托管沙盒中继配置文件。
preferredTunnel	—	首选 ffl 隧道，例如 default、default:web、cloudflare、ngrok 或 bore。调用方提供的值会覆盖自动配置文件选择。
port	—	本地 HTTP 服务端口（默认自动检测）。适用于固定隧道。
invite	False	在本地浏览器中打开 ffl 邀请页面，并显示生成的共享链接。
enableReporting	False	启用 ffl 诊断错误报告。默认禁用。
upload	—	上传至 FFL 服务端，而非使用 P2P——例如 "1 day"、"6 hours"（需要 Standard+ 账户）
resumeUpload	False	恢复中断的上传
proxy	—	代理 URL，例如 socks5://127.0.0.1:9050

fflShareFile / fflShareFiles 的附加选项：

选项	默认值	描述
preview	False	在返回的链接后附加 ?preview=true，使 ffl 下载页面直接打开完整预览视图，而非普通的浮动卡片。
exclude	—	要排除的 Glob 或正则表达式模式，以逗号分隔——例如 *.pyc,__pycache__ 或 re:\.env$
pause	—	在 1 到 99 的百分比处暂停服务端上传。需要 upload。
vfs	False	作为 VFS 服务端公开（vfs:// URI）——仅适用于 fflShareFile
preferredTunnel	—	为本次及后续运行设置首选隧道——cloudflare、ngrok、bore 等

preview 只会影响返回链接的查询字符串，适用于任何共享（单个文件、文件夹或多个文件）。预览辅助接口（/manifest、/file、/thumb——预览页面背后的清单/缩略图数据）是独立且始终启用的机制：无论是否启用 preview，MCP 都会自动为文件夹共享和多文件共享启动这些接口，而单文件共享则绝不会启动。

托管沙盒策略： 在 ChatGPT Work、Grok Bot、云托管的 Codex 沙盒或 Claude Code 云会话中（Claude Code 网页版 / claude.ai/code，或从 Claude 应用启动的远程会话），应立即使用 forceRelay=True 和 preferredTunnel="default:web"。这些环境可能只允许通过代理进行出站 HTTPS 通信，不支持可用的 UDP/ICE 或原始 TCP 隧道。此规则不适用于本地 Claude Code CLI、本地 Codex CLI、本地 Grok Build 或普通用户设备。

响应字段： sessionId、link、pid、transportDecision、qrCode?（当 qrInTerminal=True 时为 ASCII 图案）、debugLogPath?。transportDecision 会报告所选模式、原因、是否自动选择以及实际生效的 preferredTunnel。

从远程 Agent 分享

fflHowToShareFromRemoteAgent() 提供操作指南，供 Grok Bot 等云托管助手在用户要求分享其自己电脑上的文件或文件夹时使用。它会指示助手在那台电脑上操作，在存在现有 ffl/ffl.com 时使用它，或查找随已安装的 ffl-mcp 或 ffl-python 包附带的运行时，而不依赖固定的内部包路径。本地 Agent（如 Claude Code、Codex 和 Cursor）会直接使用 fflShareFile，无需此工具。

下载

fflDownload(url, outputPath?, resume?, authUser?, authPassword?,
            recipientAuth?, pickupCode?, recipientPrivateKey?, proxy?,
            enableReporting?)
  -> {ok, returncode, outputPath?, transferMode?, transferInfo?, message?, ...}

下载 FastFileLink URL（尽可能使用 WebRTC P2P，否则回退到 HTTP）或任意 HTTP(S) URL（功能类似 wget）。

transferMode	含义
webrtc_p2p	通过 WebRTC 直接进行点对点传输（最快）
p2p_tcp / p2p_quic	通过原始 TCP/QUIC 直接进行点对点传输
http_fallback	P2P 失败时使用 HTTP 中继
http_direct	常规 HTTP 下载（非 FastFileLink URL）

对于需要身份验证的链接：传入 recipientAuth + pickupCode（取件模式），或 recipientPrivateKey（公钥模式）。 仅当你想选择启用 ffl 诊断错误报告以便排查问题时，才设置 enableReporting=True。

生成密钥

fflKeygen(name?) -> {ok, returncode, output}

生成用于无密码 pubkey 收件方身份验证的 RSA 密钥对：

• <name>.fflpub — 分享给发送方（作为 recipientPublicKey 传入）
• <name>.fflkey — 妥善保管私钥（下载时作为 recipientPrivateKey 传入）

会话管理

• fflListSessions() — 列出活动分享会话
• fflStopSession(sessionId) — 终止会话
• fflGetSession(sessionId) — 获取会话详情
• fflGetSessionEvents(sessionId, limit=50) — 获取 Webhook 事件

---

注意事项

• FFL_USE_STDIN=1 可避免将文本/base64 载荷写入磁盘。
• 文件夹和多文件预览会启动本地 Webhook 服务，以便 FFL 注册预览路由。
• FFL_DEBUG=1 会将 ffl 输出保存到临时日志文件；路径通过 debugLogPath 返回。设置 FFL_DEBUG=/path/to/log.txt 可使用固定路径。
• ALLOWED_BASE_DIR 会将 fflShareFile/fflShareFiles 的操作限制在指定目录内。
• 安装期间，ffl-mcp 会并行探测 example.com 和 stun.cloudflare.com，最长等待 0.5 秒。如果所有应答都处于合成的 198.18.0.0/15 范围内，它会注册 FFL_NETWORK_PROFILE=synthetic-dns-198-18；之后分享会立即通过 default:web 使用中继，而不再等待 P2P。发生超时、失败、应答不一致或处于普通网络时，不会写入任何配置。
• 将 --env FFL_NETWORK_PROFILE=p2p 传给 install 可覆盖安装时的检测结果；也可在单次尝试直接 P2P 时，将分享工具的 transport 值设为 p2p。

---

测试

# Unit + binary tests (no network needed)
python -m unittest discover -s tests -p "*Test.py" -v

# All tests including share/download round-trips (requires network)
FFL_INTEGRATION_TESTS=1 python -m unittest discover -s tests -p "*Test.py" -v