MCP 服务器

Firebase MCP

Firebase MCP 服务器提供了一个标准化的接口来与 Firebase 服务进行交互，包括 Firebase Authentication、Firestore 和 Firebase Storage。

Tools

firestore_add_document

Add a document to a Firestore collection

firestore_list_collections

List collections in Firestore. If documentPath is provided, returns subcollections under that document; otherwise returns root collections.

firestore_list_documents

List documents from a Firestore collection with optional filtering

firestore_get_document

Get a document from a Firestore collection

firestore_update_document

Update a document in a Firestore collection

firestore_delete_document

Delete a document from a Firestore collection

auth_get_user

Get a user by ID or email from Firebase Authentication

storage_list_files

List files in a given path in Firebase Storage

storage_get_file_info

Get file information including metadata and download URL

README

Firebase MCP 服务器

概述

模型上下文协议 (MCP) 是一个开放协议，使 LLM 客户端应用程序能够使用工具并访问外部数据源。此 MCP 服务器允许任何支持 MCP 协议的 LLM 客户端与 Firebase 服务交互，包括：

身份验证: 用户管理和验证
Firestore: 文档数据库操作
Storage: 文件存储和检索

该服务器通过 MCP 工具公开 Firebase 服务，使 LLM 客户端（包括 Claude Desktop、Cursor、Roo Code 和 Cline）可以访问这些服务，同时处理身份验证和连接管理。

🔥 v1.3.0 中的新功能：集合组查询

Firebase MCP 现在支持查询 Firestore 中的子集合（集合组）！这允许您查询所有具有相同名称的子集合，而不管它们的父文档如何 - 从而可以轻松地通过单个查询搜索整个数据库层次结构。非常适合跨文档搜索、活动提要和统一仪表板。

设置

安装 Firebase MCP 服务器的最简单方法是将 llms-install.md 文件提供给您的 LLM 客户端（如 Cline）。

1. Firebase 配置

转到 Firebase 控制台
导航到项目设置 > 服务帐户
点击“生成新的私钥”
安全地保存 JSON 文件

2. 环境变量

服务器需要以下环境变量：

SERVICE_ACCOUNT_KEY_PATH: Firebase 服务帐户密钥 JSON 文件的路径（必需）
FIREBASE_STORAGE_BUCKET: Firebase Storage 的存储桶名称（可选）
- 如果未提供，则默认为 [projectId].appspot.com

3. 安装 MCP 服务器

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

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
Cursor: [project root]/.cursor/mcp.json
Roo Code (VS Code Extension): (~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json)
Cline (VS Code Extension): ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.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"
    }
  }
}

手动安装

安装依赖项

git clone https://github.com/gannonh/firebase-mcp
cd firebase-mcp
npm install

构建项目

npm run build

测试您的安装

为了确保一切正常运行，只需提示您的客户端：Please run through and test all of your Firebase MCP tools. (请运行并测试您的所有 Firebase MCP 工具。)

功能

身份验证工具

auth_get_user: 按 ID 或电子邮件获取用户详细信息

{
  identifier: string // 用户 ID 或电子邮件地址
}

Firestore 工具

firestore_add_document: 向集合添加文档

{
  collection: string,
  data: object
}

firestore_list_collections: 列出可用的集合

{
  documentPath?: string, // 可选的父文档路径
  limit?: number,        // 默认值：20
  pageToken?: string     // 用于分页
}

firestore_list_documents: 列出文档，带有可选的过滤

{
  collection: string,
  filters?: Array<{
    field: string,
    operator: string,
    value: any
  }>,
  limit?: number,
  pageToken?: string
}

firestore_get_document: 获取特定的文档
```
{
  collection: string,
  id: string
}
```

firestore_update_document: 更新现有的文档

{
  collection: string,
  id: string,
  data: object
}

firestore_delete_document: 删除文档
```
{
  collection: string,
  id: string
}
```

firestore_query_collection_group: 查询所有子集合中的文档 🆕

{
  collectionId: string,       // 要跨所有文档查询的集合 ID
  filters?: Array<{           // 可选的过滤器
    field: string,
    operator: string,         // ==, !=, <, <=, >, >=, array-contains, array-contains-any, in, not-in
    value: any
  }>,
  orderBy?: Array<{           // 可选的排序字段
    field: string,
    direction?: 'asc' | 'desc' // 默认值：'asc'
  }>,
  limit?: number,             // 要返回的最大文档数（默认值：20，最大值：100）
  pageToken?: string          // 用于分页的令牌
}

Storage 工具

storage_list_files: 列出目录中的文件

{
  directoryPath?: string, // 可选路径，默认为根目录
  pageSize?: number,      // 每页的项目数，默认为 10
  pageToken?: string      // 用于分页的令牌
}

storage_get_file_info: 获取文件元数据和下载 URL

{
  filePath: string // Storage 中文件的路径
}

开发

构建

npm run build

测试

该项目使用 Vitest 进行测试。可以针对 Firebase 模拟器运行测试，以避免影响生产数据。

安装 Firebase 模拟器

npm install -g firebase-tools
firebase init emulators

启动模拟器
```
firebase emulators:start
```
运行测试
```
npm run test:emulator
```

架构

服务器分为三个主要组件：

src/
├── index.ts              # 服务器入口点
└── lib/
    └── firebase/
        ├── authClient.ts       # 身份验证操作
        ├── firebaseConfig.ts   # Firebase 配置
        ├── firestoreClient.ts  # Firestore 操作
        └── storageClient.ts    # Storage 操作

每个客户端模块都实现特定的 Firebase 服务操作，并将它们公开为 MCP 工具。

贡献

Fork 存储库
创建一个功能分支
实施更改并进行测试（需要 80%+ 的覆盖率才能通过 CI 工作流程）
提交 pull request

许可证

MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件

故障排除

常见问题

“指定的存储桶不存在”错误

如果您在尝试访问 Firebase Storage 时遇到此错误：

检查您的 Firebase 项目是否已启用 Storage
- 转到 Firebase 控制台
- 导航到 Storage
- 如果尚未完成，请完成初始设置
验证正确的存储桶名称
- 默认存储桶名称通常为 [projectId].appspot.com
- 某些项目改用 [projectId].firebasestorage.app
- 您可以在 Firebase 控制台的 Storage 下找到您的存储桶名称
设置 FIREBASE_STORAGE_BUCKET 环境变量
- 将正确的存储桶名称添加到您的 MCP 配置
- 示例："FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"

“Firebase 未初始化”错误

如果您看到此错误：

验证您的服务帐户密钥路径
- 确保 SERVICE_ACCOUNT_KEY_PATH 中的路径正确且绝对
- 检查文件是否存在且可读
检查服务帐户权限
- 确保服务帐户具有您正在使用的 Firebase 服务所需的权限
- 对于 Storage，服务帐户需要 Storage Admin 角色

“此查询需要复合索引”错误

如果您在使用带有过滤器或排序的 firestore_query_collection_group 时看到此错误：

按照错误消息中提供的 URL 创建所需的索引
创建索引后（可能需要几分钟），重试您的查询
对于具有多个字段的复杂查询，您可能需要创建多个索引

JSON 解析错误

如果您看到有关无效 JSON 的错误：

确保代码中没有 console.log 语句
- 所有日志记录都应使用 console.error，以避免干扰 JSON 通信
- MCP 协议使用 stdout 进行 JSON 通信
检查请求中的语法错误
- 验证所有参数的格式是否正确
- 检查字段名称中是否存在拼写错误