Firebase MCP 服务器

概览

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

• 认证：用户管理和验证
• Firestore：文档数据库操作
• 存储：文件存储和检索

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

🔥 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 存储桶名称（可选）
  • 如果未提供，默认为 [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 扩展): (~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json)
• Cline (VS Code 扩展): ~/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

测试您的安装

为了确保一切正常，请提示您的客户：请运行并测试所有的 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_list_files: 列出目录中的文件

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

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

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

开发

构建

npm run build

测试

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

1. 安装 Firebase 模拟器

   npm install -g firebase-tools
   firebase init emulators
   

2. 启动模拟器

   firebase emulators:start
   

3. 运行测试

   npm run test:emulator
   

架构

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

src/
├── index.ts              # Server entry point
└── lib/
    └── firebase/
        ├── authClient.ts       # Authentication operations
        ├── firebaseConfig.ts   # Firebase configuration
        ├── firestoreClient.ts  # Firestore operations
        └── storageClient.ts    # Storage operations

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

贡献

1. 叉分仓库
2. 创建功能分支
3. 实现变更并编写测试（通过 CI 工作流需要达到80%以上的覆盖率）
4. 提交拉取请求

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

相关资源

• 模型上下文协议
• Firebase 文档
• Firebase Admin SDK

故障排除

常见问题

"指定的存储桶不存在" 错误

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

1. 检查您的 Firebase 项目是否已启用 Storage

   • 转到 Firebase 控制台
   • 导航到 Storage
   • 如果尚未完成初始设置，请完成它

2. 验证正确的存储桶名称

   • 默认存储桶名称通常是 [projectId].appspot.com
   • 有些项目使用的是 [projectId].firebasestorage.app
   • 您可以在 Firebase 控制台的 Storage 下找到您的存储桶名称

3. 设置 FIREBASE_STORAGE_BUCKET 环境变量

   • 将正确的存储桶名称添加到您的 MCP 配置中
   • 示例："FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"

"Firebase 未初始化" 错误

如果您看到此错误：

1. 验证您的服务账户密钥路径

   • 确保 SERVICE_ACCOUNT_KEY_PATH 中的路径是正确且绝对的
   • 检查文件是否存在且可读

2. 检查服务账户权限

   • 确保服务账户具有您正在使用的 Firebase 服务所需的必要权限
   • 对于 Storage，服务账户需要 Storage Admin 角色

"此查询需要复合索引" 错误

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

1. 根据错误消息提供的 URL 创建所需的索引
2. 一旦创建了索引（可能需要几分钟），请重试您的查询
3. 对于包含多个字段的复杂查询，您可能需要创建多个索引

JSON 解析错误

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

1. 确保代码中没有 console.log 语句

   • 所有日志记录应使用 console.error 以避免干扰 JSON 通信
   • MCP 协议使用 stdout 进行 JSON 通信

2. 检查请求中的语法错误

   • 确认所有参数格式正确
   • 检查字段名称是否有拼写错误