@fload-ai/mcp

中文文档
0.14.0发布于 2026/11/09MITTypeScriptES Module近 30 天下载 1987

Fload's MCP server on stdio: a thin proxy to Fload's remote MCP server with your API key. Mobile app analytics, reviews, ASO, ads and agents for AI clients.

原始使用文档
文档目录11 节
  1. Two ways to connect
  2. Remote (recommended): OAuth 2.1
  3. Local stdio: API key (this package)
  4. What you can ask your agent
  5. Tools
  6. Moving from 0.12 (the hand-written tools)
  7. Permissions
  8. Configuration (stdio)
  9. Skill
  10. Issues & feedback
  11. License

@fload-ai/mcp

MCP server for Fload: connects any MCP-compatible AI client (Claude, ChatGPT, Cursor, VS Code, Cline) to your mobile apps' App Store Connect and Google Play data, reviews, ad campaigns, ASO and Fload's agents.

There is one Fload MCP server, at https://api.fload.com/mcp. Connect to it with OAuth (remote clients) or with an API key through this package. Either way you get the same tools.

Two ways to connect

For Claude Desktop, Cursor, ChatGPT and any client that supports remote MCP servers. No API keys to manage, scoped to one organization, revocable from Fload Settings → Connected Apps.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "fload": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.fload.com/mcp"]
    }
  }
}

Restart Claude Desktop. On first use, mcp-remote opens a browser for OAuth consent. Pick which Fload organization to share, approve its permissions, done.

Cursor: Settings → MCP → Add remote server → https://api.fload.com/mcp.

ChatGPT (Team / Enterprise): Admin portal → Connectors → Add custom connector → server URL https://api.fload.com/mcp.

Local stdio: API key (this package)

For scripts, CI, headless environments, or a long-lived machine credential. This package is a thin proxy: it speaks MCP on stdio and relays every message to https://api.fload.com/mcp with your API key.

  1. Create an API key at platform.fload.com/settings/api-keys. Choose what it can do (read only, read and propose changes, or full access including approvals, or each permission), and when it expires. A tool the key has no permission for answers with the permission it needs.

  2. Add to your MCP config:

    {
      "mcpServers": {
        "fload": {
          "command": "npx",
          "args": ["-y", "@fload-ai/mcp"],
          "env": {
            "FLOAD_API_KEY": "fload_sk_your_key_here"
          }
        }
      }
    }
    

    Or use ~/.fload/config.json:

    {
      "apiKey": "fload_sk_your_key_here",
      "apiUrl": "https://api.fload.com"
    }
    

An API key acts in its own organization, in the name of the person who made it. It is never that person's own login, so work only a person approves (publishing screenshots, a custom product page's screenshots and its submit to Apple's review, turning auto mode on) stays theirs, in the Fload app or over their own OAuth connection.

What you can ask your agent

  • "Why did iOS installs drop yesterday?"
  • "Draft replies to my last 5 one-star reviews in my brand voice."
  • "What did my Apple Search Ads campaigns spend this week, and what did they bring?"
  • "Audit my ASO for my top-grossing app and suggest title changes."

Tools

The server lists its tools, each with a title, a description, its input and the MCP safety hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). Start with listAssets: every app-level tool takes the app's id as assetId.

Changes never publish in one step: a tool that changes a listing, an Apple Ads campaign, a review reply or an experiment stages an item in the Fload inbox. Read it with getActionItem, and approve it with approvePendingAction or commandActionItems only when the person asks.

Moving from 0.12 (the hand-written tools)

0.13 replaces the package's own tools with the server's. Your agent keeps working:

  • The old names (list_apps, get_metrics, get_reviews, approve_action, …) still answer on an API key connection, as aliases of the server's tools. Each says which tool it stands for; use that name. The old names stay for two more minor versions.
  • send_review_reply now stages the reply in the inbox and returns its actionItemId. Nothing is sent until the reply is approved (approve_action or approvePendingAction).
  • send_chat_message is gone: it ran a whole Fio chat turn, and your agent already has Fload's tools. list_conversations and get_conversation still read your chat history.
  • trigger_aso_analysis reads the app's App Store listing again; it never ran an ASO analysis. list_agents, list_pending_actions and get_ads_performance take the app's assetId.
  • The package no longer exports FloadApiClient, registerTools or the ./tools and ./api-client entry points.

Permissions

API keys and OAuth connections share one set of permissions. The OAuth consent screen asks for them; an API key is created with them.

  • Reads: read:apps, read:org, read:reviews, read:analytics, read:ads, read:aso, read:agents
  • Writes: write:reviews, write:ads, write:aso, write:agents, write:chat, write:org
  • OAuth identity only: openid, email, profile, offline_access

read:org covers the organization's members, its pending invitations and its apps' share links (each share link opens an app's shared page to anyone holding it). read:apps does not reach them.

read:org is deliberately not in the scopes an OAuth client gets when it registers without asking for any: it shows people's email addresses, so a client has to ask for it, and the person sees it on the consent screen before allowing it. A key or connection made before read:org existed (16 October 2026, 20:15 Danish time) that holds every read permission there was then (read:apps, read:reviews, read:analytics, read:ads, read:aso, read:agents), as every full-access or read-only key did, counts as having it. A narrower one, or one made since without read:org, has to be made again with it.

write:org changes the organization's settings: adding apps (an added app can change your bill), share links, your own notification settings, which Slack and Discord channels get Fload's updates, a data sync and feedback to Fload. Adding apps and share links (each opens an app's shared page to anyone holding it) are done only from a person's own OAuth login, never with an API key. Unlike read:org, it is never counted as held: a key or connection made before it existed, even with full access, has to be made again with it.

Removing an app (asset_delete) and inviting or removing a member (member_invite, member_remove) work like the Fload web app's dialogs. Only an owner or admin can make these changes, and only from their own OAuth login, never with an API key. Each asks first: it changes nothing and answers NEEDS_CONFIRMATION with what will happen and a confirmId. Your agent shows you that, and only after you say yes does it call asset_delete_confirm, member_invite_confirm or member_remove_confirm. A confirm works once, only for you, in that organization, within 15 minutes. Leave your client's approval prompt on for the confirm tools.

Approving an Apple Ads, listing or review change in the inbox takes that area's write permission (write:ads, write:aso or write:reviews) and write:agents (Approve and run).

Configuration (stdio)

VariableRequiredDefaultDescription
FLOAD_API_KEYYes—API key, format fload_sk_...
FLOAD_API_URLNohttps://api.fload.comThe Fload API (its /mcp is used)

Set them in your MCP client's env for the server, or put the key in ~/.fload/config.json. From 0.13.2 the server no longer reads a .env file from the directory it is started in.

FLOAD_API_URL is where FLOAD_API_KEY goes. A key in ~/.fload/config.json goes to the apiUrl saved with it, or to https://api.fload.com when there is none, never to FLOAD_API_URL (from 0.13.3), so a shell pointed at a local or preview server cannot send it there.

Skill

skill/SKILL.md (in the package) teaches an agent how to combine Fload's tools. Copy it into your agent's skills folder.

Issues & feedback

File bugs or feature requests at github.com/fload-ai/mcp/issues. For integration support: [email protected].

License

MIT

版本与发布记录

@fload-ai/mcp 共发布 24 个版本,首次发布于 2026/03/18;过去 12 个月发布了 24 个版本。

版本发布日期距今
0.14.0latest2026/11/096 天前
0.13.52026/11/069 天前
0.13.42026/11/069 天前
0.13.32026/10/3017 天前
0.13.22026/10/2224 天前
0.13.12026/10/2026 天前

关于 @fload-ai/mcp 的常见问题

@fload-ai/mcp 是什么?

Fload's MCP server on stdio: a thin proxy to Fload's remote MCP server with your API key. Mobile app analytics, reviews, ASO, ads and agents for AI clients.

如何安装 @fload-ai/mcp?

在项目目录运行 npm install @fload-ai/mcp,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 fload-mcp,可以用 npx fload-mcp 直接运行。

@fload-ai/mcp 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@fload-ai/mcp 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@fload-ai/mcp 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@fload-ai/mcp 可以商用吗?

@fload-ai/mcp 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@fload-ai/mcp 的下载量有多少?

根据 npm 官方下载统计,@fload-ai/mcp 在 2026/10/15 – 2026/11/13 这 30 天内被下载 1,987 次,日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@fload-ai/mcp 还在维护吗?

最新版本 0.14.0 发布于 2026/11/09(6 天前);至今共发布 24 个版本,其中过去 12 个月发布了 24 个;首次发布于 2026/03/18。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。