# @gannonh/firebase-mcp 中文文档

规范地址：https://npmcn.com/package/%40gannonh/firebase-mcp/

版本：1\.4\.9
npm 元数据更新时间：2025-05-10T16:18:14.061Z
中文译文更新时间：2026-11-15T22:42:46.428Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gannonh/firebase-mcp
原文对照：https://npmcn.com/package/%40gannonh/firebase-mcp/?lang=original
项目主页：https://github.com/gannonh/firebase-mcp#readme
源码仓库：https://github.com/gannonh/firebase-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：266 kB，30 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=16\.0\.0
- 运行依赖：5 个
- 首次发布：2025-03-08T20:50:51.868Z
- 最新版本发布：2025-05-10T16:18:13.884Z
- 近 30 天下载量：6476（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 0 个）

## 中文简介

通过示范背景协议与Firebase服务互动的 Firebase MCP 服务器

## 安装

```sh
npm install @gannonh/firebase-mcp
```

也可以使用：`pnpm add @gannonh/firebase-mcp`、`yarn add @gannonh/firebase-mcp`、`bun add @gannonh/firebase-mcp`

## README

# 火场MCP

![Project Logo](https://npmcn.com/package/%40gannonh/firebase-mcp/assets/logo.png)

[![Firebase MCP server](https://glama.ai/mcp/servers/x4i8z2xmrq/badge)](https://glama.ai/mcp/servers/x4i8z2xmrq)

[![Firebase Tests CI](https://github.com/gannonh/firebase-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/gannonh/firebase-mcp/actions/workflows/tests.yml)

## 概览

**火场MCP** 使AI助理能够直接与Firebase服务合作,包括:

-   **消防车**: 文档数据库操作
-   **存储**: 具有强大上传能力的文件管理
-   **认证**: 用户管理和核查

服务器与 MCP 客户端应用程序合作, 例如 [克劳德桌面](https://claude.ai/download), (中文(简体) ), [增强码](https://docs.augmentcode.com/setup-augment/mcp), (中文(简体) ), [VS 代码](https://code.visualstudio.com/docs/copilot/chat/mcp-servers),以及 [光标](https://www.cursor.com/)。 。 。 .

> ⚠️ **已知问题**编号: `firestore_list_collections` 工具可能返回客户端日志中的 Zod 验证错误。 这在MCP SDK中是一个错误的验证错误,因为我们的调查证实答复中没有布尔值. 尽管有错误消息,但查询仍然正确,并返回适当的收集数据. 这是一个日志级别错误,不影响功能.

## QQ 快速启动

### 先决条件

-   具有服务账户证书的消防基地项目
-   节点.js 环境

### 1\. 安装 MCP 服务器

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

-   克劳德桌面 : `~/Library/Application Support/Claude/claude_desktop_config.json`
-   增强: `~/Library/Application Support/Code/User/settings.json`
-   光标 : `[project root]/.cursor/mcp.json`

MCP服务器可以通过npx(被推荐)手动安装或在运行时间安装. 您如何安装决定您的配置 :

#### Npx 配置( 建议)

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

#### 本地安装配置

```json
{
  "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工具"

## QQ 设置配置( S)

### 1\. 消防基地配置

1.  转到 [火地控台](https://console.firebase.google.com/) 项目设置 服务账户
2.  点击“ 生成新私人密钥 ”
3.  安全保存 JSON 文件

### 2\. 环境变量

#### 需求

-   `SERVICE_ACCOUNT_KEY_PATH`: 您的 Firebase 服务账户密钥的路径( 需要)

#### 可选

-   `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 代码/ 增加

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

#### 光标

编辑 : `[project root]/.cursor/mcp.json`

## API 参考

### 消防工具

| 工具 | 说明 | 所需参数 |
| --- | --- | --- |
| `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` |

## QQ 开发者指南

### 安装和大楼

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

### 运行测试

首先,安装并启动 Firebase 模拟器:

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

然后运行测试:

```bash
# Run tests with emulator
npm run test:emulator

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

### 项目结构

```bash
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 传输运行服务器 :

```bash
# 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 端点 :

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

### 会话管理

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

## \* 解决问题

### 共同问题

#### 未找到存储桶

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

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

#### 启动失败

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

1.  检查您的服务账户密钥路径是否正确和绝对
2.  确保服务账户对消防基地服务有适当的授权

#### 所需综合指数

如果您收到“ 此查询需要综合索引” 错误 :

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

#### Zod 校验错误 `firestore_list_collections`

如果您看到 Zod 验证错误, 信件“ 期望对象 ” , 在使用时为布尔 `firestore_list_collections` 工具:

> ⚠️ **已知问题**编号: `firestore_list_collections` 工具可能返回客户端日志中的 Zod 验证错误。 这在MCP SDK中是一个错误的验证错误,因为我们的调查证实答复中没有布尔值. 尽管有错误消息,但查询仍然正确,并返回适当的收集数据. 这是一个日志级别错误,不影响功能.

### 调试

#### 启用文件日志

为了帮助诊断问题, 您可以启用文件记录 :

```bash
# 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 客户端配置中启用日志 :

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

#### 实时日志查看

要实时查看日志 :

```bash
# 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检查员提供交互式调试:

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

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

## 答复格式

### 存储上传响应示例

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

显示为用户 :

```markdown
## 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.  叉子存储器
2.  创建特性分支
3.  通过测试实施变革(需要80+%覆盖)
4.  提交拉动请求

## 许可证

麻省理工学院执照 - 看 [自由主义](https://npmcn.com/package/%40gannonh/firebase-mcp/LICENSE) 详细文件

## 有关资源

-   [示范背景协议文档](https://github.com/modelcontextprotocol)
-   [Firebase 文档](https://firebase.google.com/docs)
-   [消防基地管理员SDK](https://firebase.google.com/docs/admin/setup)

## 常见问题

### @gannonh/firebase-mcp 是什么？

通过示范背景协议与Firebase服务互动的 Firebase MCP 服务器

### 如何安装 @gannonh/firebase-mcp？

在项目目录运行 npm install @gannonh/firebase-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 firebase-mcp，可以用 npx firebase-mcp 直接运行。

### @gannonh/firebase-mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gannonh/firebase-mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @gannonh/firebase-mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=16\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @gannonh/firebase-mcp 可以商用吗？

@gannonh/firebase-mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gannonh/firebase-mcp 的下载量有多少？

根据 npm 官方下载统计，@gannonh/firebase-mcp 在 2026/10/16 – 2026/11/14 这 30 天内被下载 6,476 次，日均约 216 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gannonh/firebase-mcp 还在维护吗？

最新版本 1\.4\.9 发布于 2025/05/11（1\.5 年前）；至今共发布 18 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/03/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。