Firebase MCP

项目Logo

概述

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": "/绝对路径/到/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "您的项目ID.firebasestorage.app"
    }
  }
}

配置为本地安装

{
  "firebase-mcp": {
    "command": "node",
    "args": [
      "/绝对路径/到/firebase-mcp/dist/index.js"
    ],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/绝对路径/到/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "您的项目ID.firebasestorage.app"
    }
  }
}

2. 测试安装

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

🛠️ 设置与配置

1. Firebase配置

转到 Firebase控制台 → 项目设置 → 服务账户
点击"生成新的私钥"
安全保存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工具

工具	描述	必需参数
`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

然后运行测试：

# 使用模拟器运行测试
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现在除了默认的stdio传输外，还支持HTTP传输。这允许您将服务器作为独立的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，用于在请求之间维护状态。

🔍 故障排除

常见问题

存储桶未找到

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

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

Firebase初始化失败

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

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

需要复合索引

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

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

`firestore_list_collections` 的Zod验证错误

如果您在使用firestore_list_collections工具时看到带有"Expected object, received boolean"消息的Zod验证错误：

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

调试

启用文件日志记录

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

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

# 记录到自定义位置
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": "您的项目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"

📋 响应格式化

存储上传响应示例

{
  "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": "您的项目.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)**