使用说明

Firebase MCP

概述

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

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

服务器与MCP客户端应用程序配合使用，例如克劳德桌面, 增强代码, VS代码，以及光标.

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

⚡ 快速开始

先决条件

带有服务帐户凭据的Firebase项目
Node.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配置（推荐）

{
  "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代码/增强

编辑： ~/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，用于维护请求之间的状态。

🔍 故障排除

常见问题

找不到储物桶

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

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

Firebase初始化失败

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

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

需要综合指数

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

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

Zod验证错误 `firestore_list_collections`

如果在使用时看到Zod验证错误，并显示消息“预期对象，收到布尔值” firestore_list_collections 工具：

⚠️ 已知问题：The 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检查器提供交互式调试：

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