Firebase MCP

Name: Firebase MCP
Author: gannonh

项目标志

Firebase 测试 CI

概述

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

Firestore ：文档数据库操作
存储：具有强大上传功能的文件管理
身份验证：用户管理和验证

该服务器与 MCP 客户端应用程序（例如Claude Desktop 、 Augment Code 、 VS Code和Cursor）配合使用。

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

Related MCP server: Firebase App Distribution API MCP Server

⚡ 快速入门

先决条件

具有服务帐户凭据的 Firebase 项目
Node.js 环境

1. 安装 MCP 服务器

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

Claude 桌面： ~/Library/Application Support/Claude/claude_desktop_config.json
增强： ~/Library/Application Support/Code/User/settings.json
游标： [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 配置

前往Firebase 控制台→ 项目设置 → 服务帐户
点击“生成新的私钥”
安全保存 JSON 文件

2.环境变量

必需的

SERVICE_ACCOUNT_KEY_PATH ：Firebase 服务帐户密钥 JSON 的路径（必需）

选修的

FIREBASE_STORAGE_BUCKET ：Firebase 存储桶名称（默认为[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.客户端集成

克劳德桌面

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

VS Code/增强

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

光标

编辑： [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_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 传输

Firebase MCP 现在除了默认的 stdio 传输之外，还支持 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，用于维护请求之间的状态。

🔍 故障排除

常见问题

未找到存储桶

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

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

Firebase 初始化失败

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

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

需要综合指数

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

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

`firestore_list_collections`的 Zod 验证错误

如果您在使用firestore_list_collections工具时看到 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 检查器

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)**