firebase-mcp

Name: firebase-mcp
Author: gannonh

作者：gannonh229 星标更新：2025-10-27

安装使用来源：spider==github.com

项目介绍

Firebase MCP

概述

Firebase MCP 允许AI助手直接与Firebase服务进行交互，包括：

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

该服务器支持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配置

转到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. 客户端集成

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_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  # 存储操作

🌐 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工具时看到带有消息“期望对象，但接收到了布尔值”的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": "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 Inspector

MCP Inspector提供交互式调试：

# 安装MCP Inspector
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": "your-project.appspot.com"
}

显示给用户：

## 文件成功上传！ 📁

您的文件已上传至Firebase存储：

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

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