Firebase MCP

Firebase MCP

概述

Firebase MCP 支持 AI 助手直接使用 Firebase 服务，包括：

• Firestore：文档数据库操作
• Storage：文件管理，支持可靠的上传功能
• Authentication：用户管理和验证

此 MCP 服务可与 Claude Desktop、Augment Code、VS Code 和 Cursor 等 MCP 客户端应用配合使用。

⚠️ 已知问题：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：[project root]/.cursor/mcp.json

MCP 服务可以手动安装，也可以在运行时通过 npx 安装（推荐）。安装方式决定了配置方法：

配置 npx（推荐）

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

配置本地安装

{
  "firebase-mcp": {
    "command": "node",
    "args": [
      "/absolute/path/to/firebase-mcp/dist/index.js"
    ],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/absolute/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

编辑：[project root]/.cursor/mcp.json

📚 API 参考

Firestore 工具

工具	描述	必需参数
firestore_add_document	向集合添加文档	collection、data
firestore_list_documents	列出文档并进行筛选	collection
firestore_get_document	获取指定文档	collection、id
firestore_update_document	更新现有文档	collection、id、data
firestore_delete_document	删除文档	collection、id
firestore_list_collections	列出根集合	无
firestore_query_collection_group	跨子集合查询	collectionId

Storage 工具

工具	描述	必需参数
storage_list_files	列出目录中的文件	无（可选：directoryPath）
storage_get_file_info	获取文件元数据和 URL	filePath
storage_upload	根据内容上传文件	filePath、content
storage_upload_from_url	根据 URL 上传文件	filePath、url

身份验证工具

工具	描述	必需参数
auth_get_user	根据 ID 或电子邮件获取用户	identifier

💻 开发者指南

安装与构建

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

然后运行测试：

# Run tests with emulator
npm run test:emulator

# Run tests with coverage
npm run test:coverage:emulator

项目结构

src/
├── index.ts                  # Server entry point
├── utils/                    # Utility functions
└── lib/
    └── firebase/              # Firebase service clients
        ├── authClient.ts     # Authentication operations
        ├── firebaseConfig.ts   # Firebase configuration
        ├── firestoreClient.ts # Firestore operations
        └── storageClient.ts  # Storage operations

🌐 HTTP 传输

除了默认的 stdio 传输方式，Firebase MCP 现在还支持 HTTP 传输。这使你可以将服务作为独立的 HTTP 服务运行，以供多个客户端访问。

使用 HTTP 传输运行

如需使用 HTTP 传输运行服务：

# Using environment variables
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 node dist/index.js

# Or with 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，用于在请求之间保持状态。

🔍 故障排除

常见问题

未找到 Storage 存储桶

如果看到“指定的存储桶不存在”错误：

1. 在 Firebase Console → Storage 中检查存储桶名称
2. 在 FIREBASE_STORAGE_BUCKET 环境变量中设置正确的存储桶名称

Firebase 初始化失败

如果看到“Firebase 未初始化”错误：

1. 检查服务账号密钥路径是否正确且为绝对路径
2. 确保服务账号拥有 Firebase 服务所需的权限

需要复合索引

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

1. 查找错误消息中提供的 URL
2. 按照链接在 Firebase Console 中创建所需索引
3. 创建索引后重试查询（可能需要几分钟）

使用 firestore_list_collections 时出现 Zod 验证错误

如果使用 firestore_list_collections 工具时，看到错误消息为“Expected object, received boolean”的 Zod 验证错误：

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

调试

启用文件日志记录

为帮助诊断问题，你可以启用文件日志记录：

# Log to default location (~/.firebase-mcp/debug.log)
DEBUG_LOG_FILE=true npx @gannonh/firebase-mcp

# Log to a custom location
DEBUG_LOG_FILE=/path/to/custom/debug.log npx @gannonh/firebase-mcp

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

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

实时查看日志

要实时查看日志：

# Using tail to follow the log file
tail -f ~/.firebase-mcp/debug.log

# Using a split terminal to capture stderr
npm start 2>&1 | tee logs.txt

使用 MCP Inspector

MCP Inspector 提供交互式调试功能：

# Install MCP Inspector
npm install -g @mcp/inspector

# Connect to your MCP server
mcp-inspector --connect stdio --command "node ./dist/index.js"

📋 响应格式

存储上传响应示例

{
  "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"
}

向用户显示为：

## File Successfully Uploaded! 📁

Your file has been uploaded to Firebase Storage:

**File Details:**
- **Name:** reports/quarterly.pdf
- **Size:** 1024000 bytes
- **Type:** application/pdf
- **Last Updated:** April 11, 2025 at 15:37:10 UTC

**[Click here to download your file](https://storage.googleapis.com/bucket/reports/quarterly.pdf?alt=media)**

🤝 参与贡献

1. Fork 此仓库
2. 创建功能分支
3. 实现更改并编写测试（要求覆盖率达到 80% 以上）
4. 提交拉取请求

📄 许可证

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

🔗 相关资源

• Model Context Protocol 文档
• Firebase 文档
• Firebase Admin SDK