BagOS

🚀 安装

npx bagos-mcp-server

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "bagos": {
      "command": "npx",
      "args": ["-y", "bagos-mcp-server"],
      "env": {
        "BAGS_API_KEY": "your-key-here"
      }
    }
  }
}

Claude Code：

claude mcp add bagos --env BAGS_API_KEY=your-key-here -- npx -y bagos-mcp-server

重启客户端，然后对它说：“显示 Bags 创作者排行榜”。服务启动时会将配置报告输出到 stderr；如果缺少配置，它会告知你缺少哪个变量以及原因。

仅凭 API 密钥即可使用 11 个只读工具中的 8 个。其中 3 个——bags_heartbeat、 bags_get_claimable_fees 和 bags_authenticate——会报告你的钱包信息，因此还需要 BAGS_KEYPAIR_PATH，否则会报错。在完成配置之前，写入操作始终处于关闭状态（入门指南）。

🔒 为什么可以放心交给助手使用

• 首次调用不会签名。 写入工具会返回预览，以及一个与这些确切参数绑定的一次性令牌指纹；在你再次调用并提供该令牌之前，不会有任何内容发送到链上。
• SOL 硬性上限。 默认每笔交易上限为 0.1，每个会话上限为 1；超过上限的操作会在调用 Bags SDK 之前被拒绝。
• 默认使用 Devnet。 写入操作仅限主网，因此未配置的安装不会花费真实资金。

完整的威胁模型、披露政策和各项控制措施的限制： .github/SECURITY.md。

⚠️ 如果你使用过 1.x——v2.0.0 修复了一项严重缺陷

v2.0.0 修复了一项严重缺陷。 在 1.x 中，写入工具会构建交易后将其丢弃，却报告操作成功——实际上从未签名或提交任何交易。如果你使用过 1.x，并以为交易或领取操作已执行，事实并非如此。详见 CHANGELOG.md。

2.x 已在 npm 上发布，运行 npx bagos-mcp-server 安装的就是该版本——详见最新版本。每个版本都附带 npm provenance——软件包 tarball 通过加密方式证明其与此代码库及构建它的提交相对应。 1.x 已在 npm 上弃用。如果你仍在使用，请升级。

---

📦 收录平台

---

💡 问题与解决方案

问题

一个能转移资金的 MCP 服务，会把签名密钥交给 AI 助手。助手作出决定时，交易可能已经上链，而人类还没来得及读到相关信息。协议中没有任何机制会让模型暂停，也没有任何机制能限制一条被误解的指令所能花费的金额。

解决方案

Bags 是一个 Solana 代币发行平台，其标志性功能是创作者费用分成：代币交易费用会在链上分配给发行者和推广者，且可随时领取。因此，“谁能从这个代币中获益、可领取多少，以及如何领取”构成了一项真实的工作流，而 BagOS 正是为此实现自动化。

BagOS 让 AI 助手读取 Bags/Solana 代币数据，并在明确确认后，通过你的钱包执行兑换并领取创作者费用。除非你进行配置，否则写入功能默认关闭；这些操作仅支持主网，而且首次调用写入工具时不会签名任何内容：它会返回预览和一个一次性令牌，该令牌仅授权其签发时对应的确切参数。

🏗️ 架构与技术栈

每次写入都要经过以下流程：

token gate → spend caps → confirmation → simulate → sign → send → confirm

工具	类型	功能
bags_heartbeat	只读	服务状态和钱包可达性
bags_get_token_analytics	只读	代币铸造地址的累计手续费数据
bags_get_creators	只读	按累计手续费排名的代币创作者
bags_get_trade_quote	只读	兑换报价，不会执行交易。
bags_get_claimable_fees	只读	当前可由你的钱包领取的手续费
bags_get_partner_stats	只读	合作伙伴配置的领取统计
bags_get_token_claim_stats	只读	各创作者的累计领取额——包含已领取金额的版税名单
bags_get_token_claim_events	只读	代币的领取审计记录，支持分页
bags_get_token_creators	只读	哪些人分享代币手续费及其分成比例
bags_resolve_launch_wallet	只读	社交账号（twitter/tiktok/kick/github）→手续费分成钱包
bags_authenticate	只读	通过 Ed25519 签名验证钱包所有权
bags_prepare_token_metadata	受控	创建代币信息和元数据。不会发行代币。
bags_execute_trade	写入	兑换代币，进行签名并提交。
bags_claim_fees	写入	领取创作者/LP 手续费，进行签名并提交。

bags_prepare_token_metadata 会预留一个铸造地址并上传元数据。完成发行还需要 Meteora 手续费分成配置，其中的手续费领取者分配必须由你决定——因此，此服务不会实现这一步， 以免擅自猜测。请前往 bags.fm 完成发行。

---

🔐 写入工具与支出控制

除非进行配置，否则写入功能处于关闭状态，并且仅支持主网。

**Bags 没有 devnet 部署。**其 API 端点以及 Meteora/手续费分成程序 ID 均属于主网。 尽管如此，此服务默认使用 devnet，因此未配置的安装无法花费真实资金。 在 devnet 上调用写入工具会返回说明，而不是晦涩难懂的程序错误。

首次调用写入工具时不会进行任何签名。它会返回预览和一个一次性令牌：

⚠️  CONFIRMATION REQUIRED — nothing has been signed or sent.

Action:  Swap 0.05 of So1111…1112
         for       EkJuyY…dBAGS
         expect    4823917722 (min 4679199990)
         slippage  3%
         network   🔴 MAINNET — real funds

Spend:   0.05 SOL
Caps:    0.1 SOL/tx · 0/1 SOL used this session

To execute, call bags_execute_trade again with the identical arguments plus:
  confirm: "kR3nT9xQm2vP"

该令牌是工具名称与确切参数的指纹，因此，为 0.01 SOL 兑换签发的令牌无法授权 10 SOL 的兑换。 令牌会在 5 分钟后过期，并且无论结果如何都会被使用，因此无法重放。

成功后，你会获得真实签名和区块浏览器链接——如果交易未上链，绝不会返回成功消息。

设置 BAGS_ALLOW_UNCONFIRMED=true 可跳过预览。支出上限仍然有效。

**这些上限仅适用于 SOL。**如果兑换的输入是其他代币，就无法以 SOL 为单位估值，因此无法设置上限。 默认情况下，这类兑换会被拒绝；设置 BAGS_ALLOW_UNCAPPED_TOKEN_SWAPS=true 即可允许此类兑换， 预览中会明确说明该交易不设上限。

---

⛓️ 实际部署

一笔真实交易，通过生产写入流程上链，并从链上重新获取，而非相信返回值：

签名	2kvu25xW…U5Dm
集群	devnet
Slot	484219564
状态	err: null
记录日期	2026-08-16

你可以运行 npm run proof:devnet 亲自复现——它会通过水龙头为一次性密钥对注入资金， 使用与写入工具相同的模拟 → 签名 → 发送 → 确认流程提交一笔转账，然后从链上重新获取该签名。 函数返回 success 只是一个说法；可以在区块浏览器中打开的签名才是证据。完整方法见 DEMO.md。

---

📊 工程严谨性

418 个测试。针对支出上限和确认步骤的绕过测试至关重要；应将对此处的修改视为安全变更。这些测试经过手动验证，针对的是刻意注入的变更：删除上限保护、确认检查、精度查询或支出记录器，都会导致测试套件失败。这是手动验证，并非自动化的变异测试阶段——此仓库没有可重新运行的变异测试配置。

层级	状态	详情
真实默认路径	✅	所有已记录的命令中都没有终止开关标记。USE_MOCK_DATA 默认为关闭；启用时，它只影响 bags_get_claimable_fees 工具，并在该工具自己的响应中添加 ⚠️ [MOCK DATA ENABLED]。其他 13 个工具会忽略它。DEMO.md 中提供了实时运行凭证
代码质量	✅	ESLint + tsc --noEmit，均无问题
单元测试	✅	Jest，418 个测试 / 19 个套件，语句 · 分支 · 函数 · 行覆盖率均为 100%，并强制执行
高信号测试	✅	经变异验证的上限/确认绕过测试 · 泄漏通道回归测试（API 密钥曾被回显到工具输出中）· 网络不匹配拒绝测试
安全性	✅	CodeQL SAST · Dependabot SCA · 对完整历史记录运行 gitleaks（fetch-depth: 0）· 已启用密钥扫描 + 推送保护 · CI 中的 npm audit 作为递增门槛——见下文
依赖债务	⚠️	6 条安全公告，0 条严重——从 90 条降至此数。所有可修补项均已通过限定版本的 overrides 清除（见 package.json）。剩下的 6 条都源于同一个根本问题：bigint-buffer GHSA-3gc7-fjrx-p6mg，它沿依赖链向上到 @bagsfm/bags-sdk 的每一层都会计数一次。bigint-buffer 没有已修补版本——1.1.5 是已安装版本，也是最新版本，但仍存在漏洞。CI 会阻止任何严重问题，以及任何超出 .audit-baseline.json 的新增问题。注意： npm 只会在根项目中应用 overrides，因此这些保护仅适用于此仓库和 CI，不适用于已发布软件包的使用者。
CI	✅	4 个阶段（质量 → 安全 ∥ 测试 → 构建），采用 cancel-in-progress 并发策略；Node 22 + 24 矩阵；软件包产物和入口点检查
CD	✅	发布 → tarball 审计 → npm publish --provenance → 弃用被取代的版本。另一个工作流通过 OIDC 将 server.json 提交至 MCP 注册表。两者均须通过完整 CI 套件后才能执行。npm 上的 1.0.0 已弃用，并附有指向其所带缺陷的说明。
链上证明	✅	npm run proof:devnet 通过生产写入路径提交真实交易，并从链上重新获取该交易。捕获于 2026-08-16：2kvu25xW…U5Dm，slot 484219564，err: null。任何人都可以重新验证——见 DEMO.md
社区规范	✅	行为准则 · 贡献指南 · 安全策略 · issue + PR 模板

我们特意未纳入 E2E 浏览器测试和 Lighthouse 预算：这是一个 stdio/HTTP MCP 服务，没有 Web UI，因此两者都无法测出任何结果。最接近端到端覆盖的是 npm run demo，它通过真实 MCP JSON-RPC 调用线上 API，驱动五个读取工具——bags_heartbeat、bags_get_creators、bags_get_trade_quote、bags_get_partner_stats 和 bags_authenticate。其余读取工具仅由单元测试覆盖。

---

🚀 开始使用

前置条件

你需要从 dev.bags.fm 获取 Bags API 密钥。仅凭此密钥即可启用只读工具。要进行交易和领取手续费，你还需要 Solana 密钥对文件和门控代币——见 写入工具与支出控制。

启用写入

在以下各项全部设置之前，写入功能都会保持关闭：

{
  "mcpServers": {
    "bagos": {
      "command": "npx",
      "args": ["-y", "bagos-mcp-server"],
      "env": {
        "BAGS_API_KEY": "your-key-here",
        "BAGS_NETWORK": "mainnet",
        "BAGS_KEYPAIR_PATH": "~/.config/bags/keypair.json",
        "BOS_TOKEN_MINT": "Feqmy64uNvK198MAWFC5ujRnzif6kM9wKonTX2t3BAGS",
        "BAGS_MAX_SOL_PER_TX": "0.1",
        "BAGS_MAX_SOL_PER_SESSION": "1.0"
      }
    }
  }
}

⚠️ BOS_TOKEN_MINT 目前有两个用途。 它既是门控要求你持有的代币（上文的 $BOS），也是未指定代币时兑换的默认输出代币（ExecuteTrade.ts）。这两种用途对代币的要求正好相反：门控要求你持有某种代币，而兑换目标则需要有流动性的代币，但 $BOS 几乎没有流动性。调用 bags_execute_trade 时，请务必显式传入 outputMint，不要依赖默认值。将这两项拆分为两个变量的问题已作为已知问题跟踪。

配置

变量	必填	默认值	说明
BAGS_API_KEY	是	—	来自 dev.bags.fm
BAGS_NETWORK	否	devnet	devnet 或 mainnet。写入需要使用 mainnet。
SOLANA_RPC_URL	否	公共集群 RPC	必须与 BAGS_NETWORK 一致，否则服务将拒绝启动
BAGS_KEYPAIR_PATH	仅写入时需要	~/.config/bags/keypair.json	JSON 字节数组密钥对文件
BOS_TOKEN_MINT	仅写入时需要	—	门控代币铸币地址
BOS_REQUIRED_BALANCE	否	10000	门控代币的最低余额。0 会禁用门控（任何余额均可通过）；非数字值会导致启动时拒绝运行，而不是静默使用默认值。
BAGS_MAX_SOL_PER_TX	否	0.1	单笔交易支出上限
BAGS_MAX_SOL_PER_SESSION	否	1.0	单个进程的支出上限
BAGS_ALLOW_UNCONFIRMED	否	false	跳过确认步骤
BAGS_ALLOW_UNCAPPED_TOKEN_SWAPS	否	false	允许输入代币不是 SOL 的兑换。这些上限以 SOL 计价，无法限制此类兑换。
HELIUS_RPC_URL	否	—	SOLANA_RPC_URL 未设置时，作为其别名读取
USE_MOCK_DATA	否	false	true 会使 bags_get_claimable_fees 返回虚构余额，并标注为虚构数据。不会影响其他工具。
BAGS_API_URL	否	https://public-api-v2.bags.fm/api/v1	覆盖 bags_authenticate 使用的 Bags API 基础 URL。由于工具会对该端点发送的内容签名，因此必须是 bags.fm 或其子域名上的 https 地址。
BAGS_ALLOW_CUSTOM_API_URL	否	false	true 会取消对 BAGS_API_URL 的 bags.fm 限制。仅用于你控制的服务。
BAGS_ENV_FILE	否	—	要加载的环境文件的绝对路径。不会自动加载工作目录中的 .env，因为 MCP 客户端的工作目录取决于你当前打开的项目。
PORT	否	3050	HTTP 监听端口。仅在使用 --http 启动时读取。

---

🧪 测试与 CI

npm ci
npm run ci            # lint + typecheck + tests with coverage
npm run dev           # stdio server with watch
npm run inspector     # MCP Inspector against the built server
npm run proof:devnet  # land a real devnet transaction through the write path

proof:devnet 使用持久化的一次性密钥对（位于 .proof/，已加入 gitignore），并在需要时从 devnet 水龙头为其注资，然后通过写入工具使用的同一套模拟/签名/发送/确认流程发起转账，最后再从链上重新获取签名，而不是相信函数的返回值。最后这一步才是关键：函数返回 success 只是一种说法，而能在区块浏览器中打开的签名才是证据。

---

📽️ 演示材料

• DEMO.md — 针对 Bags 主网线上 API 的真实运行记录：7 个场景、8 个步骤、每步延迟，以及网络不匹配保护和代币门控拒绝写入的实例。
• docs/examples.md — 你可以输入给助手的提示词，以及每个提示词应触发的操作。
• docs/KNOWN_ISSUES.md — 当前存在的问题及其原因，包括已排除的原因。尚未解决的警示也会在此说明，而不会留给你自行发现。

---

🛡️ 安全

在将有资金的钱包用于此项目之前，请阅读 SECURITY.md。

概要：私钥从磁盘读取，用于签名，绝不会记录到日志、发送到任何地方或放入错误消息中。工具错误只会返回消息，不包含堆栈跟踪，并会对类似密钥的字符串进行脱敏。启动报告会从 RPC URL 中移除凭据。如果 RPC 端点的集群与 BAGS_NETWORK 不一致，服务会拒绝启动，而不会在显示 devnet 标识的情况下签署 mainnet 交易。

同一规则现在也适用于 Bags API 密钥：bags_authenticate 会将其写入 ~/.config/bags/credentials.json，并且只显示末尾四个字符。以前它会完整打印密钥，导致有效凭据泄露到助手的上下文以及其下游的所有对话记录中。如果你在此更改之前的版本中运行过 bags_authenticate，请前往 dev.bags.fm 轮换该密钥。

这些控制措施的已知局限

有两点值得在此说明，而不是留在 SECURITY.md 中：

• HTTP 模式没有身份验证。 使用 --http 启动时，服务会在 0.0.0.0 上监听，采用宽松的 CORS 策略且不进行身份验证，因此任何能够访问该端口的调用方都可以调用写入工具——共用一个支出计数器。请勿在有资金的钱包上运行 HTTP 模式。 stdio 是默认模式，也是本项目唯一推荐的传输方式；这也是 Smithery 列表仅提供 stdio 而非托管服务的原因。
• 会话上限会将结果未知的交易计入。 如果发送后确认超时，支出仍会计入（交易可能仍会成功），并且错误中会包含签名。在区块链浏览器上确认情况后，重启服务即可重置计数器。

请通过 GitHub 安全公告报告漏洞。

---

📄 许可证

MIT — 参见 LICENSE。