Firebase MCP

概述

Firebase MCP 使 AI 助手能够直接与 Firebase 服务协同工作，包括：

• Firestore：文档数据库操作
• Storage：具有强大上传功能的文件管理
• Authentication：用户管理和验证

该服务器可与 MCP 客户端应用程序协同工作，例如 Claude Desktop、Augment Code、VS Code 和 Cursor。

⚠️ 已知问题：firestore_list_collections 工具可能在客户端日志中返回 Zod 验证错误。这是 MCP SDK 中的错误验证，因为我们调查确认响应中不存在布尔值。尽管错误消息显示，查询仍然正常工作并返回正确的集合数据。这是一个日志级别的错误，不会影响功能。

⚡ 快速入门

前置条件

• 具有服务账户凭证的 Firebase 项目
• Node.js 环境

1. 安装 MCP 服务器

将服务器配置添加到您的 MCP 设置文件：

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Augment: ~/Library/Application Support/Code/User/settings.json
• Cursor: [项目根目录]/.cursor/mcp.json

MCP 服务器可以手动安装或通过 npx 在运行时安装（推荐）。您如何安装决定了您的配置：

配置为 npx（推荐）

{
  "firebase-mcp": {
    "command": "npx",
    "args": [
      "-y",
      "@gannonh/firebase-mcp"
    ],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/绝对路径/to/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"
    }
  }
}

配置为本地安装

{
  "firebase-mcp": {
    "command": "node",
    "args": [
      "/绝对路径/to/firebase-mcp/dist/index.js"
    ],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/绝对路径/to/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"
    }
  }
}

2. 测试安装

询问您的 AI 客户端："请测试所有 Firebase MCP 工具。"

🛠️ 设置与配置

1. Firebase 配置

1. 前往 Firebase 控制台 → 项目设置 → 服务账户
2. 点击 "生成新的私钥"
3. 安全保存 JSON 文件

2. 环境变量

必填

• SERVICE_ACCOUNT_KEY_PATH：Firebase 服务账户密钥 JSON 路径（必填）

可选

• FIREBASE_STORAGE_BUCKET：Firebase Storage 的存储桶名称（默认为 [projectId].appspot.com）
• MCP_TRANSPORT：使用的传输类型（stdio 或 http）（默认为 stdio）
• MCP_HTTP_PORT：HTTP 传输的端口（默认为 3000）
• MCP_HTTP_HOST：HTTP 传输的主机（默认为 localhost）
• MCP_HTTP_PATH：HTTP 传输的路径（默认为 /mcp）
• DEBUG_LOG_FILE：启用文件日志：
  • 设置为 true 将记录到 ~/.firebase-mcp/debug.log
  • 设置为文件路径将记录到自定义位置

3. 客户端集成

Claude Desktop

编辑：~/Library/Application Support/Claude/claude_desktop_config.json

VS Code / Augment

编辑：~/Library/Application Support/Code/User/settings.json

Cursor

编辑：[项目根目录]/.cursor/mcp.json

📚 API 参考

Firestore 工具

Storage 工具

认证工具

💻 开发者指南

安装与构建

git clone https://github.com/gannonh/firebase-mcp
cd firebase-mcp
npm install
npm run build

运行测试

首先，安装并启动 Firebase 模拟器：

npm install -g firebase-tools
firebase init emulators
firebase emulators:start

然后运行测试：

# 使用模拟器运行测试
npm run test:emulator

# 运行带覆盖的测试
npm run test:coverage:emulator

项目结构

src/
├── index.ts                  # 服务器入口
├── utils/                    # 工具函数
└── lib/
    └── firebase/              # Firebase 服务客户端
        ├── authClient.ts     # 认证操作
        ├── firebaseConfig.ts   # Firebase 配置
        ├── firestoreClient.ts # Firestore 操作
        └── storageClient.ts  # Storage 操作

🌐 HTTP 传输

Firebase MCP 现在支持 HTTP 传输，除了默认的 stdio 传输。这允许您将服务器作为独立的 HTTP 服务运行，供多个客户端访问。

使用 HTTP 传输运行

要使用 HTTP 传输运行服务器：

# 使用环境变量
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 node dist/index.js

# 或使用 npx
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npx @gannonh/firebase-mcp

HTTP 客户端配置

使用 HTTP 传输时，配置您的 MCP 客户端连接到 HTTP 端点：

{
  "firebase-mcp": {
    "url": "http://localhost:3000/mcp"
  }
}

会话管理

HTTP 传输支持会话管理，允许多个客户端连接到同一服务器实例。每个客户端都会收到一个唯一的会话 ID，用于在请求之间保持状态。

🔍 故障排除

常见问题

存储桶未找到

如果您看到 "指定的存储桶不存在" 错误：

1. 验证 Firebase 控制台 → Storage 中的存储桶名称
2. 在 FIREBASE_STORAGE_BUCKET 环境变量中设置正确的存储桶名称

Firebase 初始化失败

如果您看到 "Firebase 未初始化" 错误：

1. 检查服务账户密钥路径是否正确且为绝对路径
2. 确保服务账户具有 Firebase 服务的适当权限

复合索引要求

如果您收到 "此查询需要复合索引" 错误：

1. 查看错误消息中提供的 URL
2. 跟随链接在 Firebase 控制台创建所需的索引
3. 索引创建后重试查询（可能需要几分钟）

firestore_list_collections 的 Zod 验证错误

如果您在使用 firestore_list_collections 工具时看到消息为 "预期对象，收到布尔值" 的 Zod 验证错误：

⚠️ 已知问题：firestore_list_collections 工具可能在客户端日志中返回 Zod 验证错误。这是 MCP SDK 中的错误验证，因为我们调查确认响应中不存在布尔值。尽管错误消息显示，查询仍然正常工作并返回正确的集合数据。这是一个日志级别的错误，不会影响功能。

调试

启用文件日志

要帮助诊断问题，您可以启用文件日志：

# 记录到默认位置 (~/.firebase-mcp/debug.log)
DEBUG_LOG_FILE=true npx @gannonh/firebase-mcp

# 记录到自定义位置
DEBUG_LOG_FILE=/路径/to/custom/debug.log npx @gannonh/firebase-mcp

您也可以在 MCP 客户端配置中启用日志：

{
  "firebase-mcp": {
    "command": "npx",
    "args": ["-y", "@gannonh/firebase-mcp"],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/路径/to/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app",
      "DEBUG_LOG_FILE": "true"
    }
  }
}

实时日志查看

要实时查看日志：

# 使用 tail 跟踪日志文件
tail -f ~/.firebase-mcp/debug.log

# 使用分割终端捕获 stderr
npm start 2>&1 | tee logs.txt

使用 MCP 检查器

MCP 检查器提供交互式调试：

# 安装 MCP 检查器
npm install -g @mcp/inspector

# 连接到您的 MCP 服务器
mcp-inspector --connect stdio --command "node ./dist/index.js"

📋 响应格式

Storage 上传响应示例

{
  "name": "reports/quarterly.pdf",
  "size": "1024000",
  "contentType": "application/pdf",
  "updated": "2025-04-11T15:37:10.290Z",
  "downloadUrl": "https://storage.googleapis.com/bucket/reports/quarterly.pdf?alt=media",
  "bucket": "your-project.appspot.com"
}

向用户显示为：

## 文件成功上传！ 📁

您的文件已上传到 Firebase Storage：

**文件详情：**
- **名称：** reports/quarterly.pdf
- **大小：** 1024000 字节
- **类型：** application/pdf
- **最后更新：** 2025年4月11日 15:37:10 UTC

**[点击此处下载您的文件](https://storage.googleapis.com/bucket/reports/quarterly.pdf?alt=media)**

🤝 贡献

1. 分支仓库
2. 创建功能分支
3. 实现带测试的更改（要求覆盖率 80%+）
4. 提交拉取请求

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

🔗 相关资源

• 模型上下文协议文档
• Firebase 文档
• Firebase Admin SDK