基于MCP协议与FCM构建AI助手移动推送通知系统

1. 项目概述一个连接MCP与FCM的推送桥梁最近在折腾一些自动化工作流经常需要在不同的服务和应用之间传递消息和通知。比如一个脚本运行成功了或者服务器出了点小状况如果能第一时间推送到手机上那处理起来就从容多了。我尝试过不少方案从简单的邮件、到各种IM的Webhook再到一些专门的推送服务总觉得要么配置太繁琐要么推送不够及时要么就是功能太单一。直到我遇到了kibotu/mcp-fcm-push这个项目。它的名字听起来有点技术化简单来说它就是一个“翻译官”或者“适配器”。它能把来自MCP的消息翻译成FCM能听懂的语言然后通过 FCM 这个全球性的推送服务把消息精准地送到你的手机App上。MCP 是Model Context Protocol的缩写你可以把它理解为一套标准化的“对话”协议让AI助手比如Claude、Cursor里的AI能够安全、可控地访问和使用外部工具和数据。而 FCM 则是Firebase Cloud Messaging是谷歌提供的一套非常稳定、跨平台的推送服务我们手机上很多App的推送都是靠它实现的。所以这个项目的核心价值就出来了它为AI助手通过MCP协议提供了一个向移动设备发送推送通知的能力。想象一下你正在和AI讨论一个复杂的部署脚本AI执行完后可以直接通过这个工具告诉你“部署成功服务已启动在8080端口”这条消息会像微信消息一样出现在你的手机通知栏里。或者你让AI监控某个API的健康状态一旦出现异常它能立刻报警。这极大地扩展了AI助手的“触手”让它从纯粹的对话工具变成了一个能主动触达你、与你交互的智能助手。这个项目适合谁呢我认为主要三类人第一类是重度AI工具使用者尤其是那些把Claude、Cursor等深度集成到工作流中的开发者或运维人员第二类是喜欢折腾自动化、希望打通不同服务间通知的极客第三类则是任何需要构建一个“AI驱动的事件响应系统”的开发者这个项目提供了一个非常轻量且标准化的通知出口。2. 核心架构与设计思路拆解2.1 为什么是MCP FCM的组合要理解这个项目的设计首先要明白它为什么选择这两个技术栈。这背后是开发者对当前AI应用生态和移动通知现状的深刻洞察。MCPModel Context Protocol的崛起与价值过去让AI使用外部工具比如搜索、读写文件、调用API是个麻烦事每个AI平台如OpenAI的GPTs、Anthropic的Claude都有自己的插件或工具调用方式没有统一标准。MCP的出现就是为了解决这个问题。它定义了一套标准协议让“AI客户端”如Claude Desktop、Cursor可以通过一个统一的“服务器”来访问各种工具。这个项目本质上就是一个实现了特定工具发送推送的MCP服务器。选择MCP意味着这个推送能力可以无缝地被所有支持MCP协议的AI客户端使用兼容性极佳未来可扩展性也强。FCMFirebase Cloud Messaging的不可替代性在移动推送领域FCM几乎是安卓生态的“官方”选择在iOS上也有很好的支持。它解决了推送最头疼的几个问题保活App在后台也能收到、省电统一的消息通道比各自维护长连接更节能、高送达率依托谷歌服务穿透性强。自己实现一套推送系统需要处理不同设备的令牌管理、连接保持、消息排队、重试等复杂问题而FCM把这些都封装好了。所以项目选择FCM作为底层推送引擎是一个非常务实且可靠的选择把复杂度交给了谷歌自己专注于业务逻辑的“翻译”。项目的核心定位协议转换与身份桥接。因此这个项目的架构非常清晰它作为一个独立的服务MCP Server运行。当AI客户端MCP Client想要发送推送时它会按照MCP协议向这个服务器发起一个请求。服务器收到请求后并不直接与手机通信而是将请求中的内容标题、正文、数据等按照FCM API要求的格式进行封装。然后它使用预先配置好的FCM服务账号密钥向FCM服务器发起一个HTTPS请求。最终由FCM负责将这条消息推送到目标设备上。整个过程中本项目只做“协议转换”和“身份认证使用服务账号调用FCM API”这两件事架构简洁职责单一。2.2 关键组件与数据流分析让我们更具体地拆解一下这个项目运行时的核心组件和数据流向这对于后续的部署和调试至关重要。MCP 客户端比如你电脑上运行的 Claude Desktop并且你已经配置它连接到了本地的mcp-fcm-push服务器。当你在与Claude的对话中说“嘿帮我测试一下服务器如果ping通了就通知我。” Claude理解后就会通过MCP协议调用本项目的send_push_notification工具。MCP-FCM-Push 服务器这是本项目的核心。它持续运行监听来自MCP客户端的连接。它内部主要包含MCP协议处理器解析客户端发来的JSON-RPC请求提取出工具名send_push_notification和参数token,title,body等。FCM客户端一个配置了FCM服务账号JSON密钥的HTTP客户端。它的职责是构建一个符合FCM v1 API标准的HTTP POST请求。消息构造器将MCP请求中的参数映射到FCM消息对象的结构中。例如MCP的title对应FCM的notification.titlebody对应notification.body。对于更复杂的数据负载则放入data字段。FCM 云端服务谷歌的服务器集群。它接收来自我们服务器的请求进行认证和校验然后根据消息中的设备注册令牌token将消息放入对应的推送队列。如果目标设备在线FCM会立刻通过其维护的长连接将消息下发如果设备离线FCM会暂存消息待设备上线后再次发送有一定期限和策略。目标设备与客户端App你的手机。手机上必须安装了一个集成了FCM SDK并正确配置了的App。这个App在启动时会向FCM注册获取一个独一无二的、针对本App本设备的令牌Registration Token。这个令牌就是推送的“地址”。当FCM消息到达时系统或App会根据消息类型通知消息或数据消息弹出通知栏提示或静默处理。注意这里有一个关键概念设备令牌Device Token。这个令牌不是固定的它可能会在App重装、用户清除数据等情况下改变。因此一个健壮的实现需要你的客户端App具备将最新令牌回传到你的服务端或本项目的机制。本项目只负责“发送”不负责“令牌管理”这是设计上的一个边界需要使用者自己处理。整个数据流可以概括为AI指令 - MCP客户端 - MCP-FCM-Push服务器 - FCM云端 - 目标设备。理解了这条链任何环节出问题你都能快速定位。3. 从零开始的完整部署与配置指南理论讲清楚了我们进入实战环节。我会带你从零开始把这个服务搭起来并让Claude Desktop成功调用它。这个过程涉及几个关键平台的操作请一步步跟着来。3.1 前期准备获取FCM服务账号密钥这是整个流程中最关键、也最容易出错的一步。你需要一个Google Cloud项目和一个Firebase项目它们本质是联通的。访问 Firebase 控制台打开浏览器访问 Firebase 控制台 用你的谷歌账号登录。创建或选择项目点击“创建项目”或选择一个现有项目。给项目起个名字比如my-ai-push-demo。过程中可能会要求你启用Google Analytics根据个人需要选择即可。在项目中添加App项目创建成功后进入项目概览页。你会看到为iOS、安卓、Web添加应用的选项。这里我们不需要真正创建一个移动App但需要为服务器端访问生成密钥。点击项目设置齿轮图标。生成私钥在“设置”页面切换到“服务账号”选项卡。你会看到“Firebase Admin SDK”部分。点击“生成新的私钥”按钮。在弹出的对话框中确认然后会下载一个JSON文件例如my-ai-push-demo-firebase-adminsdk-xxxxx-xxxxxxxxxx.json。警告这个JSON文件包含了超级管理员权限的私钥绝对不要将其提交到任何公开的代码仓库如GitHub。泄露它意味着别人可以代表你的项目向任何用户发送推送甚至管理你的Firebase资源。我们后续会将其放在安全的本地路径。这个JSON文件里包含了project_id,private_key,client_email等关键信息我们的mcp-fcm-push服务器就是靠它来向FCM证明身份的。3.2 本地环境搭建与项目运行假设你已经有基本的Node.js建议18版本和npm环境。我们通过npx直接运行这是最快捷的方式。# 1. 将下载的私钥JSON文件放到一个安全目录比如 ~/.config/mcp-fcm-push/ mkdir -p ~/.config/mcp-fcm-push/ mv ~/Downloads/my-ai-push-demo-*.json ~/.config/mcp-fcm-push/service-account.json # 2. 通过npx运行mcp-fcm-push服务器 # 我们需要通过环境变量告诉它服务账号密钥的路径 GOOGLE_APPLICATION_CREDENTIALS~/.config/mcp-fcm-push/service-account.json npx kibotu/mcp-fcm-push运行上述命令后你应该会看到类似以下的输出MCP Server running on stdio Tool registered: send_push_notification这说明MCP服务器已经成功启动并在stdio标准输入输出上等待连接。这种模式是给Claude Desktop等客户端“嵌入”使用的。另一种运行方式作为独立HTTP服务器如果你想通过网络访问这个MCP服务器方便多个客户端连接可以运行GOOGLE_APPLICATION_CREDENTIALS~/.config/mcp-fcm-push/service-account.json npx kibotu/mcp-fcm-push --transport http它会提示你服务器监听的端口默认可能是3000然后你就可以通过http://localhost:3000来连接了。但Claude Desktop目前更常用stdio模式我们以第一种为准。3.3 配置Claude Desktop连接MCP服务器现在我们需要让Claude Desktop知道这个MCP服务器的存在。打开Claude Desktop应用。进入设置Settings找到“开发者”Developer设置部分。你会看到一个“编辑配置”Edit Config按钮点击它会打开一个JSON配置文件通常位于~/Library/Application Support/Claude/claude_desktop_config.json或类似路径。在这个JSON文件中你需要添加一个mcpServers配置。关键是要正确指向我们刚刚启动的本地服务器。由于我们用的是stdio传输配置如下{ mcpServers: { fcm-push: { command: node, args: [ -e, process.env.GOOGLE_APPLICATION_CREDENTIALS/full/path/to/your/service-account.json; require(kibotu/mcp-fcm-push) ] } } }重要解释fcm-push这是你给这个服务器起的名字可以自定义。command: node告诉Claude用Node.js来执行。args这里的-e表示直接执行一段字符串代码。我们在这段代码里首先设置了环境变量GOOGLE_APPLICATION_CREDENTIALS然后才导入require我们的mcp-fcm-push模块。这是确保模块在启动时能读到密钥的关键。你必须将/full/path/to/your/service-account.json替换成你实际存放JSON文件的绝对路径。例如/Users/yourname/.config/mcp-fcm-push/service-account.json。保存配置文件并完全重启Claude Desktop应用不是仅仅关闭窗口而是从任务栏/程序坞彻底退出再重新启动。重启后Claude Desktop会在后台启动你配置的MCP服务器进程。你可以打开Claude尝试输入“/tools”如果配置成功你应该能在工具列表里看到一个名为send_push_notification的工具。恭喜你桥梁已经架通了4. 核心工具使用详解与消息定制配置成功只是第一步如何用好这个工具才是关键。send_push_notification工具接收哪些参数如何发送一条有效的推送我们深入看一下。4.1 工具参数全解析当你让AI使用这个工具时AI会尝试构造一个包含以下参数的调用。你需要了解每个参数的意义参数名类型是否必填描述对应FCM字段tokenString是目标设备的FCM注册令牌。这是推送的“地址”必须从你的移动端App获取。message.tokentitleString否通知的标题会显示在通知栏顶部。message.notification.titlebodyString否通知的正文内容。message.notification.bodydataObject否一个键值对对象用于传递自定义数据。这些数据不会直接显示但可以被客户端App接收并处理用于深度链接、内部逻辑等。message.dataimageString否通知中大图的URL。FCM会下载并显示此图片需客户端和系统支持。message.notification.imagepriorityString否推送优先级。可选normal或high。对于需要即时提醒的消息如即时通讯使用high。message.android.priority/message.apns.headers.apns-priority最简调用示例AI可能会生成这样的调用请求。{ tool: send_push_notification, args: { token: fcm_token_from_your_app_here..., title: 任务完成, body: 您的数据备份已成功执行。 } }带数据负载的复杂示例{ tool: send_push_notification, args: { token: fcm_token_from_your_app_here..., title: 系统警报, body: 服务器CPU使用率超过95%, priority: high, data: { alert_type: cpu_overload, server_id: web-01, dashboard_url: https://monitor.example.com/alerts/123 } } }在这个例子中手机收到通知后用户点击通知App可以根据data里的dashboard_url直接跳转到具体的监控面板实现场景化直达。4.2 如何获取设备令牌Token这是实践中最常见的问题“我的token从哪里来” 答案来自于你的移动端App。创建一个简单的移动端App你需要一个集成了FCM SDK的App。对于测试你可以快速创建一个Flutter、React Native或原生安卓/iOS项目并按照Firebase官方文档集成FCM。在App中获取Token集成SDK后App启动时可以向FCM申请注册令牌。这个令牌需要被发送到你的后端服务保存起来。以下是一个Flutter示例的伪代码import firebase_messaging.dart; FirebaseMessaging messaging FirebaseMessaging.instance; String? token await messaging.getToken(); if (token ! null) { // 将这个token通过API发送到你的服务器保存 await saveTokenToServer(token); print(FCM Token: $token); }设计一个简单的API来接收和存储Token你可以写一个极简的HTTP服务提供一个端点如POST /register-token来接收App发来的token并将其存储到数据库或简单的文件中。对于mcp-fcm-push这个独立服务你可能需要另一个常驻的、简单的“令牌管理服务”或者更简单地在测试阶段直接将打印出来的token手动复制出来使用。实操心得在开发测试阶段我通常会在App里把获取到的Token直接以Toast或Log的形式显示出来然后手动复制到AI对话中或者写到一个临时文件里让MCP服务器去读。这样可以避免在早期就搭建复杂的令牌管理后端。对于生产环境一个可靠的、能处理Token刷新的注册/更新API是必须的。4.3 通过AI助手发送你的第一条推送一切就绪让我们在Claude里实际操作一下。确保Claude Desktop已重启且工具列表中有send_push_notification。在聊天框中你可以用自然语言直接告诉Claude“请向我的测试设备发送一条推送通知标题是‘测试消息’内容是‘Hello from Claude via MCP!’。设备令牌是[你的实际FCM Token]。”Claude会理解你的意图并自动调用send_push_notification工具。你会在聊天记录中看到它发起的工具调用请求通常以一个小部件或折叠文本的形式展示。如果一切正常几秒内你的测试手机就应该“叮”的一声收到这条推送了这个过程的神奇之处在于你不需要知道具体的API格式也不需要写任何代码。你只需要用自然语言描述需求AI和MCP工具会自动完成剩下的工作。这正是MCP生态想要实现的愿景让AI成为操作复杂工具的自然界面。5. 高级应用场景与集成模式掌握了基础推送后我们可以看看如何将这个能力融入到更复杂的自动化工作流中发挥其最大价值。5.1 场景一AI驱动的运维监控与告警这是最直接的应用。你可以让AI助手结合其他MCP工具如服务器状态检查、日志查询工具扮演一个运维助手。流程AI定期通过计划任务触发调用“检查服务器状态”工具。如果返回的指标如磁盘使用率90%则自动调用send_push_notification发送高优先级告警并在data字段中附带服务器ID和具体指标。优势告警信息不再是冰冷的文本AI可以在推送前对信息进行摘要和提炼比如“紧急主数据库服务器磁盘即将写满建议立即清理日志。”使得告警更具可读性和可操作性。5.2 场景二长时任务的完成通知当你让AI执行一个耗时较长的任务时比如“分析这份100页的PDF并总结”你不需要一直守在电脑前。流程AI开始任务前可以告诉你“任务已开始预计需要5分钟完成后我会通知您。” 在任务真正完成后AI在输出总结的同时调用推送工具发送“文档分析完成”的通知。体验提升这极大地改善了人机交互的体验让你可以放心地离开去做别的事AI会在完成后“召唤”你。5.3 场景三与自动化脚本如Zapier、n8n集成虽然MCP主要面向AI客户端但本项目作为一个HTTP服务器运行时可以被任何能发送HTTP请求的工具调用。流程在你的n8n工作流中当一个节点处理完成例如表单提交、数据库更新可以添加一个HTTP Request节点向本地运行的mcp-fcm-push的HTTP端点发送一个符合MCP JSON-RPC格式的请求。请求示例{ jsonrpc: 2.0, method: tools/call, params: { name: send_push_notification, arguments: { token: YOUR_TOKEN, title: 新订单, body: 有一笔新的订单待处理。 } } }意义这相当于为你所有的自动化工作流添加了一个强大的移动通知出口而不必在每个工作流中都去直接集成FCM的复杂API。5.4 构建一个简单的令牌管理服务进阶如前所述生产环境需要管理动态变化的设备令牌。这里提供一个极简的设计思路一个微型后端服务使用Express.js或类似框架提供两个端点POST /register接收App发来的用户标识如用户名、邮箱和设备令牌将其存储到数据库如SQLite、Redis。GET /token/:userId供mcp-fcm-push或其他服务查询某个用户的当前令牌。改造MCP-FCM-Push可选你可以fork原项目修改其调用逻辑。让它不再直接接收token参数而是接收一个userId然后在发送前去你的令牌管理服务查询对应的最新token。这样AI或调用方只需要关心“推送给谁”而不需要关心具体的、易变的设备令牌。这个方案将令牌管理的复杂性从推送逻辑中解耦出来使得系统更加健壮和可维护。6. 常见问题、故障排查与性能调优在实际使用中你肯定会遇到各种问题。下面是我踩过坑后总结的排查清单和解决方案。6.1 推送失败常见原因及排查步骤当你发送推送后手机没反应可以按照以下流程排查现象可能原因排查步骤Claude中工具调用无反应或报错1. MCP服务器未启动或配置错误。2. 服务账号密钥路径或内容错误。3. Claude Desktop配置错误。1. 检查终端运行npx命令的窗口看是否有错误日志。2. 确认GOOGLE_APPLICATION_CREDENTIALS环境变量指向的JSON文件存在且内容完整。3. 检查Claude配置文件的JSON格式是否正确路径是否为绝对路径。重启Claude。工具调用成功但手机收不到推送1. 设备令牌Token无效或已过期。2. 目标设备上的App未正确集成FCM或处于非活跃状态。3. FCM项目配置问题如未启用API。4. 网络问题设备无法连接FCM。1.这是最常见原因。在App中重新获取Token并更新到发送端。Token可能在App重装后失效。2. 确认测试App已成功集成FCM并在前台或后台运行安卓需注意省电策略。3. 前往Google Cloud Console在“API和服务”中确保“Firebase Cloud Messaging API”已启用。4. 在设备上测试网络连通性。推送延迟极高1. FCM服务端排队或网络延迟。2. 使用了normal优先级且设备处于Doze模式安卓。3. 发送端到FCM的网络不佳。1. 对于即时性要求高的消息使用priority: high。2. 测试时确保设备屏幕常亮或在前台。3. 检查发送服务器的网络出口。只有特定设备收不到1. 该设备的Token单独失效。2. 该设备品牌如某些国内定制安卓的系统限制了FCM后台活动。3. 用户手动关闭了该App的通知权限。1. 让该设备上的App重新获取Token并注册。2. 引导用户检查App的“自启动”、“电池优化”等设置允许后台运行。3. 检查系统设置中的通知权限是否开启。一个实用的调试技巧在运行mcp-fcm-push服务器时可以尝试增加日志级别。查看其源码或文档看是否支持DEBUG*这样的环境变量来输出更详细的HTTP请求和响应信息这有助于确认消息是否成功发送到了FCM以及FCM返回了什么。6.2 安全性最佳实践推送能力如果被滥用会变成骚扰工具。请务必遵循以下安全准则保护服务账号密钥如前所述私钥JSON文件等同于密码。永远不要提交到版本库。在服务器上使用安全的密钥管理服务如AWS Secrets Manager, GCP Secret Manager或至少设置严格的文件权限。验证发送请求如果你开放了HTTP接口务必增加认证层如API Key、JWT防止未授权的第三方随意发送推送。管理设备令牌实现令牌的注册和注销接口。当用户卸载App或在设置中退出登录时应调用注销接口避免向无效设备发送消息。尊重用户推送内容应相关、有价值。避免频繁发送无关通知以免用户关闭权限。6.3 性能与可靠性考量对于轻量级使用本项目直接运行即可。如果计划用于生产环境或较高频率的推送需要考虑服务化与高可用不要长期在个人电脑上用npx运行。应将其封装为一个系统服务如使用systemd, pm2并部署到可靠的服务器上确保7x24小时运行。错误处理与重试当前项目可能对FCM发送失败的处理比较简单。在生产环境中你需要考虑加入重试机制特别是对于网络瞬时故障并记录失败日志以供排查。批量发送如果需要向大量设备发送相同内容的消息目前循环调用工具的方式效率低。FCM支持批量发送和主题订阅。你可以考虑扩展本项目的功能或者在前端调用方实现批量聚合后使用FCM的批量API但需注意MCP协议可能不是最适合批量操作的接口。速率限制FCM对免费项目有发送速率限制。如果推送量非常大需要监控错误响应中的429 Too Many Requests状态码并实施适当的限流策略。7. 项目局限性与未来扩展思考kibotu/mcp-fcm-push项目作为一个专注的协议转换工具完美地完成了它的核心使命。但在实际深度使用后我也发现了一些可以改进或需要注意的边界。当前的局限性单工具设计目前只提供了一个send_push_notification工具功能相对单一。对于更复杂的推送需求如向主题发送、发送条件消息、管理设备组则无法支持。无状态管理项目本身不管理设备令牌也不处理发送状态的回执FCM可以返回消息是否成功送达的回执。这些都需要使用者自行构建外部系统来实现。依赖FCM生态这既是优点也是限制。如果你的用户群体完全无法使用谷歌服务例如某些特定区域那么FCM的送达率会大打折扣你需要考虑集成其他推送渠道如APNs for iOS或第三方推送服务。可能的扩展方向多推送渠道支持可以将其扩展为一个“统一推送网关”。除了FCM内部还可以集成苹果的APNs、华为Push等。MCP工具的参数可以设计成通用的然后由服务器根据设备类型通过Token前缀或额外参数判断自动路由到不同的推送服务。增强工具集增加新的MCP工具例如subscribe_to_topic让设备订阅一个主题。send_to_topic向某个主题的所有设备广播消息。validate_token验证一个设备令牌是否仍然有效。集成简单的令牌缓存虽然完整的令牌管理应该由外部服务负责但项目内部可以提供一个基于内存或文件的小型缓存在短时间内重复向同一令牌发送时避免重复查询外部服务提高性能。这个项目的意义远不止于“发送推送”。它更像一个样板展示了如何将一个实用的后端服务FCM优雅地封装成AI世界MCP的一个标准工具。它降低了AI获得现实世界交互能力的门槛。你可以借鉴这个模式将数据库查询、发送邮件、控制智能家居等任何API都包装成MCP工具。届时你的AI助手将真正成为一个拥有“千手千眼”的智能体而mcp-fcm-push正是那第一只伸向移动世界的手。