snowluma-file-sender
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@snowluma-file-sender把刚生成的 D:/agent-output/report.pdf 发到我的 QQ 上"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
SnowLuma QQ 文件发送工具
让本机 AI Agent 把用户指定的文件,通过 SnowLuma 发给预先配置好的 QQ 收件人。
提供 stdio MCP + CLI:准备文件 → 发送 → 查询状态。文件内容由本机 QQ 后端读取上传;模型只接触文件名、大小、校验值和发送状态。工具不调用模型 API,也不需要模型密钥。
适合“生成报告后把文件发给我”这类个人秘书任务。它只处理文件发送,不接收群消息,不提供群管理或聊天记忆功能。
需要什么
Node.js 24+、npm。
已登录 QQ 且开启 OneBot HTTP 接口的 SnowLuma,在同一台电脑运行。
网关支持扩展动作
upload_private_file。它不是 OneBot v11 标准动作,后端版本会影响实际可用性。网关进程能按相同绝对路径读取本工具的暂存文件;当前不做跨主机或容器路径映射。
本地原型已在 Windows + SnowLuma 2.1.1 完成真实 PDF 私聊发送,收件人确认能打开文件。公开版增加了配置通用化和边界检查,以自动化测试验证;其他网关、版本和操作系统的真实 QQ 传输尚未验证。
本仓库不包含 SnowLuma、QQ 或它们的安装器,也不负责启动、更新、登录这些程序。请自行安装并遵守各自许可。本工具是独立项目,与这些项目及腾讯无隶属关系。
Related MCP server: YAFL MCP Server
快速开始(PowerShell)
下载或克隆本仓库,进入目录:
npm ci --ignore-scripts
New-Item -ItemType Directory -Force D:\file-sender-home, D:\agent-output
Copy-Item .\secretary.example.json D:\file-sender-home\secretary.json编辑 D:\file-sender-home\secretary.json:将 enabled 改为 true,recipientQQ 填成自己的收件 QQ 号字符串;gatewayUrl 填本机网关地址;sourceRoots 仅允许专门存放待发送产物的目录。
{
"enabled": true,
"recipientQQ": "YOUR_QQ",
"gatewayUrl": "http://127.0.0.1:3000",
"sourceRoots": ["D:/agent-output"]
}YOUR_QQ 是占位符,必须替换才能运行。网关地址只接受 127.0.0.1 或 [::1] 的 HTTP 根地址,不接受域名、路径、查询参数或 URL 内凭据。
$env:FILE_SECRETARY_HOME = 'D:\file-sender-home'
$env:ONEBOT_ACCESS_TOKEN = '填入你本机网关的访问令牌'
node .\src\cli.js --file D:\agent-output\report.pdf --prepare-only此时只创建文件副本,尚未发出。记录返回的 deliveryId,按用户发送指令继续:
node .\src\cli.js --send-id <deliveryId>
node .\src\cli.js --status <deliveryId>也可以用 --file <绝对路径> 直接准备并发送。CLI 会在网络请求前打印记录 ID,中途退出后应先用该 ID 查状态。没有鉴权的网关可省略 ONEBOT_ACCESS_TOKEN;推荐启用网关鉴权。
Linux/macOS 的路径和环境变量语法需要相应替换。所有运行数据写在 FILE_SECRETARY_HOME;想节省系统盘空间,就把它和产物目录设在其他磁盘。
接入 MCP
只向可信本机工作 Agent开放。不要挂载到任意群成员或陌生人可以触发的聊天 Agent。
支持通用 stdio MCP 配置的客户端可参考:
{
"mcpServers": {
"snowluma-file-sender": {
"command": "node",
"args": ["D:/tools/snowluma-qq-file-sender/src/mcp.js"],
"env": {
"FILE_SECRETARY_HOME": "D:/file-sender-home",
"ONEBOT_ACCESS_TOKEN": "YOUR_LOCAL_GATEWAY_TOKEN"
}
}
}
}替换项目路径和令牌。客户端启动时须能找到 Node.js 24+;必要时把 command 写成 node.exe 的绝对路径。Codex 的 TOML 示例和 DeepSeek Harness 接入说明见 Agent 流程。
工具 | 用途 |
| 首次调用时读取流程 |
| 校验指定文件并创建不可随源文件变化的副本,返回 ID |
| 发送该副本,工具参数不能指定收件人 |
| 读取持久化状态,不再上传 |
用户提示词示例:“把刚生成的 D:/agent-output/report.pdf 用 SnowLuma 发给我。”Agent 应准备并发送同一 ID,不能先把 PDF 读成文本或 base64 交给模型。此工具不保证任意客户端支持 MCP,也不能在客户端关闭时唤醒它。
状态和恢复
状态 | 含义与处理 |
| 已创建副本,还未请求上传;24 小时内可发送 |
| 请求已开始或进程在发送期间退出;先查 QQ,不能自动重发 |
| 网关返回成功;不等于对方已经收到、下载或打开 |
| 网络、超时、响应异常或网关失败导致结果不确定;先查 QQ,不能自动重发 |
| 准备超过 24 小时,未发送;由用户决定是否重新准备 |
同一记录再次调用发送不会重复发起已开始或已完成的上传。异常退出留下的锁不会自动删除。这不是端到端“恰好一次”保证:换 ID、新建副本、删除状态目录都可能造成重复。unknown 或 sending 不能通过重新 prepare 绕过,必须先由人核实收件 QQ。
自动清理在下一次准备文件时运行:未发送副本保留 24 小时,已受理/过期记录保留 7 天;有发送锁、unknown、sending 记录继续保留。总计最多 64 条、128MiB,每个文件最多 32MiB。不确定记录长期占用额度时应人工核实后清理;本工具不提供一键重置或自动补发。
文件和隐私边界
源文件必须位于配置的允许目录内;真实路径也须在范围内,链接不能指向范围外。
配置、常见凭据文件、框架私有状态目录等名称被拦截。这只是额外护栏,不能识别任意文件内的秘密;只应将用户明确同意发送的产物放进允许目录。
准备时复制并计算 SHA-256,发送前复核副本;准备后的收件人或网关变更会阻止上传。
本地配置、暂存文件和元数据可能含有私人信息,应保护
FILE_SECRETARY_HOME,不要提交 Git。网关及 QQ 平台会处理实际文件内容。MCP 结果含文件名、大小、散列和收件人,可能被使用它的 AI 客户端记录;不返回文件正文、本地源路径或访问令牌。不收集聊天历史或遥测。
这不是抵御同一系统账号下恶意进程的沙箱;目录与配置应仅供可信用户维护。
同类项目与定位
这是一个范围较窄的可复用工具,不宣称首创 QQ 文件发送、防重发或文件校验。
项目 | 已有能力 | 本工具的定位 |
HTTP MCP 包装多种 OneBot 动作;上传依赖后端能看到文件路径 | 专门面向本机固定收件人的文件任务,直接提供 stdio 与 CLI | |
QQ/Telegram 与 Astral Code 双向桥接,提供文件工具和消息历史 | 仅做输出文件投递,不需要接收事件、聊天数据库或 Astral 会话 | |
CLI/MCP/HTTP、常驻队列、持久化 requestId 防重发和不确定状态处理 | 不需要额外接收守护进程;以准备副本、固定收件人、发送/查询为入口 | |
通用动作查询/执行,支持有根目录限制、校验和配额的文件流上传 | 组合成限定用途的文件发送流程;不向 Agent 开放通用动作执行 |
比较依据为这些项目截至 2026-10-23 的公开文档,没有对全部项目做实机性能或可靠性排名。设计说明 记录接口依据与取舍。
开发与维护
npm ci --ignore-scripts
npm test测试使用临时目录和模拟网关,不会发送真实 QQ 文件。维护者请先读 AGENTS.md、变更记录 和 设计说明。MIT 许可;来源与第三方边界见 NOTICE 和 LICENSE。
Available Tools
4 toolsdelivery_statusARead-only
查询同一 deliveryId 的本地状态,不发文件;不代表收件方已下载。
| Name | Required | Description | Default |
|---|---|---|---|
| deliveryId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's real contribution is the caveat that the status is local and does not mean the recipient downloaded — a genuinely useful scope limitation — but it says nothing about rate limits, staleness, or what the status transitions are.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact clause with the purpose and the two disambiguating caveats front-loaded; no filler sentences at all.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the burden of explaining what the returned status actually is, and it does not — the possible status values and their meaning are absent. The anti-confusion caveat is good, but an agent still cannot interpret the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the schema gives only a UUID format/pattern, so the description must carry semantic weight. '同一 deliveryId' usefully implies the id was previously obtained from a related tool rather than being an arbitrary UUID, which is meaningful added context, but nothing is said about id validity or error behavior for unknown ids.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Combines a specific verb (查询) with a specific resource (同一 deliveryId 的本地状态) and explicitly excludes file sending, which separates it from the send_file sibling. It does not, however, distinguish itself from prepare_file or file_secretary_help.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'不发文件' implicitly routes the agent away from send_file toward a polling/inspection use case, but there is no explicit statement of when to call this instead of the other siblings, nor any prerequisite such as needing a deliveryId previously issued by send_file/prepare_file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
file_secretary_helpARead-only
本机文件秘书流程。用户要求把文件发给自己时先读此工具。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully adds that this is a prerequisite step in the file-sending workflow, but it does not describe what the tool actually returns or what the agent should do after reading it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no wasted text. It is efficient, though the opening phrase '本机文件秘书流程' is somewhat compressed and could be clearer for an agent unfamiliar with the workflow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter help/prerequisite tool with annotations and no output schema, the description is minimally adequate: it says when to read it. However, it omits what the tool provides and what the agent should expect after invoking it, leaving some ambiguity about the resulting workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter semantics needed. The schema is correspondingly empty, and the description does not need to compensate for missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a 'local file secretary workflow' and tells the agent to read this tool before sending a file to the user, but it does not explicitly state what the tool returns (presumably workflow guidance/instructions). The purpose is inferable, but it is less clear than a direct verb+resource statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear trigger: when the user asks to send a file to themselves, read this tool first. It does not mention when not to use it or explicitly name sibling alternatives, so it falls short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
prepare_fileB
准备用户指定的文件副本,不发送。返回 deliveryId;收件人由本地配置固定。
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a non-read-only, non-destructive, closed-world operation, so the safety profile is covered. The description adds two useful facts beyond the annotations: no dispatch occurs and a deliveryId is returned, plus that recipients are fixed by local config. It does not say whether prepared copies expire or how long a deliveryId stays valid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short clauses: purpose first, then return value and the recipient-config caveat. Nothing is wasted, though the phrasing is terse enough that the filename format question is left silently unanswered.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, the description usefully discloses the return value (deliveryId) and the implicit-recipient behavior. It falls short on the file argument's expected form and on what happens to a prepared but unsent copy.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single required 'file' parameter, which has only min/max length constraints. The description restates it as a 'user-specified file' but gives no indication of whether the value is a path, an ID, or a URL — the one piece of information missing from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: prepare a copy of a user-specified file, explicitly noting it does not send. The negative clause ('不发送') distinguishes it functionally from the sibling send_file, though it never names that sibling outright.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies the prepare-then-send flow by contrasting with sending, and notes the recipient comes from local configuration rather than a parameter. It never states explicitly when to use this versus calling send_file directly, nor what to do with the returned deliveryId.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
send_fileADestructive
按用户指令发送已准备文件,只传 deliveryId。unknown/sending/busy 禁止自动重发。
| Name | Required | Description | Default |
|---|---|---|---|
| deliveryId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and openWorldHint=true, so the real-world irreversibility profile is covered. The description adds genuinely non-obvious context beyond that: the single deliveryId payload contract and the idempotency guard forbidding auto-resend while status is unknown/sending/busy. It falls short of explaining success/failure outcomes or what to do when blocked.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight clauses with zero waste, and the blocking rule is front-loaded right after the core action. Nothing to trim.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, open-world send with no output schema, the description should say where deliveryId comes from and what to do when the state check blocks the send. It covers the resend prohibition but leaves output/result behavior entirely undocumented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the type/format (uuid, pattern) is the only machine-readable hint. '只传 deliveryId' merely restates the single-param contract; it never says what a deliveryId is or that it originates from prepare_file, which is the key semantic an agent needs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('发送已准备文件' – send already-prepared file) and constrains the payload to deliveryId. It implicitly excludes prepare_file (this sends files that are '已准备'), but it doesn't name delivery_status or the other siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'按用户指令发送' hints at when this is used (user-directed sends), and the 'unknown/sending/busy 禁止自动重发' rule gives a concrete when-not-to-act condition. However, it never names the visible alternative – checking delivery_status first – so an agent has to infer where those states come from.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
4 tool updates
v0.1.0- First observed
delivery_status - First observed
file_secretary_help - First observed
prepare_file - First observed
send_file
TDQS
Scored across 4 tools
Each tool has a clearly distinct role: prepare creates a deliveryId, send_file sends an already prepared file, delivery_status checks local status only, and file_secretary_help documents the workflow. The boundaries between preparation, sending, and status checking are explicit.
All names use snake_case, but the convention is mixed: send_file and prepare_file are verb_noun, while delivery_status and file_secretary_help are noun-based. The names remain readable and reasonably predictable.
Four tools are well-scoped for a narrow file-sending workflow: help, prepare, send, and status. Each tool appears to earn its place without unnecessary surface area.
The set covers the core lifecycle from preparing a file to sending it and checking delivery status, plus workflow help. Minor gaps exist around canceling, listing deliveries, or handling resend/busy cases beyond the documented prohibition.
Maintenance
Related MCP Connectors
Agent file transfer. No API key to start; price downloads in USDC on Base.
- LockboxOAuthrun.lockbox
Send API keys and private files to someone else's agent, end-to-end encrypted.
Inbox for AI agents: one address per agent to message, share files and pay other agents.
Upload any file, get a tracked shareable link. DocSend for AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to send and receive files securely via JustDrop, with end-to-end encryption, QR codes, and no server-side storage.449 npmMIT

YAFL MCP Serverofficial
AlicenseNot gradedqualityDmaintenanceEnables AI agents to securely transfer files between machines via encrypted, expiring share links, with tools for upload, download, status checks, and link management.MIT- AlicenseAqualityBmaintenanceEnables agents to price, send, and track encrypted file transfers, with files chunked, encrypted, and hashed locally before any network relay, and to retrieve signed collection receipts. It supports prepaid credit pools and gives agents a privacy-first transfer capability within their own trust domain.1Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents and terminal users to dispatch local files directly to paired mobile phones or other peers over Blip's end-to-end encrypted peer-to-peer transfer, automatically discovering paired devices and avoiding desktop confirmation prompts. It also exposes tools to list paired devices and report daemon health and recent transfer history.MIT