firebase-mcp-server

Firebase MCP 服务

适用于 Firebase（Firestore、Storage、Auth、Functions Logging）的通用 Model Context Protocol（MCP）服务，提供架构驱动的验证和高效利用上下文的工具。

功能

• @ 提及支持 - 使用 @firebase:firestore://users/user-123 引用 Firestore 文档
• 智能自动补全 - MRU 缓存会跟踪访问过的文档，便于快速再次引用
• 自动发现 - 同时显示基于架构的集合和已发现的集合
• 基于路径的架构 - 遵循 Firebase firestore.rules 约定
• 架构演进 - 字段状态元数据（实验性 → 正式 → 旧版）
• 热重载 - 监视文件，架构更改后无需重启
• 灵活验证 - 三种模式：严格、警告（默认）、宽松
• 无需架构即可使用 - 通过发现模式探索未知数据库
• 高效利用上下文的工具 - 大型数据集的 Token 用量减少 99%
• 索引感知查询 - 根据 firestore.indexes.json 验证查询
• Functions 日志 - 使用类似 SQL 的查询查看 Cloud Functions 日志，并支持聚合和标签筛选

安装

将其添加到你的 MCP 客户端（例如 Claude Code）中 — 通过 npx 运行，无需全局安装：

{
  "mcpServers": {
    "firebase": {
      "command": "npx",
      "args": ["-y", "@dasasian/firebase-mcp-server", "start", "./firestore-schemas.json"]
    }
  }
}

start 接受可选的架构配置路径（默认为 ./firestore-schemas.json）和可选的索引路径（默认为 ./firestore.indexes.json）— 参见架构格式。Firebase 身份验证使用 Application Default Credentials。

或者全局安装 CLI：

npm install -g @dasasian/firebase-mcp-server
firebase-mcp start ./firestore-schemas.json

开发（从源代码构建）

npm install
npm run build
npm run cli -- start --config ./examples/basic/firestore-schemas.json

@ 提及支持（资源）

在 Claude Code 中直接引用 Firestore 文档：

What's the email for @firebase:firestore://users/user-123?
Show me all posts: @firebase:firestore://posts/*

工作原理

在 Claude Code 中输入 @firebase 时：

显示基于架构的集合（带验证）：

• 📋 用户（用户账号文档）
• 📋 帖子（博客文章文档）
• 📋 评论（文章评论）

此外还会自动发现集合（无架构）：

• 🔍 analytics
• 🔍 sessions
• 🔍 audit_logs

配置

# Enable/disable auto-discovery (default: true)
export FIRESTORE_AUTO_DISCOVER=true

# Cache duration in seconds (default: 300 = 5 minutes)
export FIRESTORE_DISCOVERY_CACHE_TTL=300

自动发现成本：每天约 $0.0003（可忽略不计）

工具

该服务提供 33 个工具，分为四组。每个工具都会声明 MCP 注解 （readOnlyHint、destructiveHint、idempotentHint、openWorldHint），因此客户端 可以自动批准读取操作，并在写入前询问。

选择要加载的工具

每个会话中加载全部 33 个工具定义约占用 12k Token 的上下文。如果 你只需要其中一部分，可以缩小范围：

# Only Firestore (12 tools, ~4.3k tokens)
firebase-mcp start --tools firestore

# Firestore plus Auth
firebase-mcp start --tools firestore,auth

也可以在 MCP 客户端配置中设置：

export FIREBASE_MCP_TOOLS=firestore,storage

--tools 标志的优先级高于环境变量。两者都未设置时会加载 所有工具，因此升级不会隐藏你已在使用的工具。调用已关闭组中的 工具时会返回错误，并指出需要启用的组。

组	工具数	约 Token 数
firestore	12	4,341
storage	14	4,152
auth	6	2,075
logs	1	1,817
全部（默认）	33	12,387

Firestore（12）— --tools firestore

• firestore_show_collections — 显示集合（读取）
• firestore_read — 读取文档（读取）
• firestore_export — 导出集合（读取）
• firestore_validate — 根据架构验证（读取）
• firestore_query_select — 查询文档（读取）
• firestore_query_collection_group — 查询集合组（读取）
• firestore_count — 统计文档数（读取）
• firestore_sum — 对字段求和（读取）
• firestore_stats — 集合统计信息（读取）
• firestore_import — 导入文档（写入，有破坏性）
• firestore_update — 更新文档（写入，有破坏性）
• firestore_delete — 删除文档（写入，有破坏性）

Firebase Auth（6）— --tools auth

• firebase_auth_list_users — 列出用户（读取）
• firebase_auth_get_user — 获取用户（读取）
• firebase_auth_create_user — 创建用户（写入）
• firebase_auth_update_user — 更新用户（写入，有破坏性）
• firebase_auth_delete_user — 删除用户（写入，有破坏性）
• firebase_auth_revoke_sessions — 撤销会话（写入，有破坏性）

Firebase Storage（14）— --tools storage

• firebase_storage_list_buckets — 列出存储桶（读取）
• firebase_storage_ls — 列出文件（读取）
• firebase_storage_stat — 文件元数据（读取）
• firebase_storage_find — 查找文件（读取）
• firebase_storage_get_url — 获取文件 URL（读取）
• firebase_storage_get_access — 获取文件访问权限（读取）
• firebase_storage_read — 将文件下载到本地临时路径（写入）
• firebase_storage_upload — 上传文件（写入，有破坏性）
• firebase_storage_rm — 删除文件（写入，有破坏性）
• firebase_storage_cp — 复制文件（写入，有破坏性）
• firebase_storage_mv — 移动文件（写入，有破坏性）
• firebase_storage_sync — 将存储桶同步到本地（写入，有破坏性）
• firebase_storage_push — 将本地内容推送到存储桶（写入，有破坏性）
• firebase_storage_set_access — 设置文件访问权限（写入，有破坏性）

Cloud Logging（1）— --tools logs

• firebase_functions_logs — 使用类似 SQL 的语法查询 Cloud Functions 日志（写入）

firebase_storage_read 和 firebase_functions_logs 未标记为只读，因为它们会写入数据：前者会下载文件到本地临时文件，后者会在磁盘上更新自动发现的日志架构。

读取函数日志需要额外的 IAM 角色。 Firebase Admin SDK 服务账号默认没有 Cloud Logging 访问权限，因此即使其他所有工具都能正常工作，firebase_functions_logs 仍会失败，并显示 PERMISSION_DENIED: Permission denied for all log views。授予该角色后，请等待几分钟让设置生效：

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:firebase-adminsdk-xxxxx@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/logging.viewAccessor"

仅授予 roles/logging.viewer 可能不够——错误信息提到了 log views，而 logging.views.access 权限属于 viewAccessor。

查询示例：

// Discover what functions exist
{"distinct": "functionName"}

// Show recent errors
{"where": [{"field": "severity", "operator": "==", "value": "ERROR"}], "limit": 20}

// Top error patterns with counts (use "message" — structured logs have no textPayload)
{"groupBy": ["message"], "aggregates": [{"field": "*", "operation": "count", "alias": "count"}], "where": [{"field": "severity", "operator": "==", "value": "ERROR"}], "orderBy": [{"field": "count", "direction": "desc"}], "limit": 10}

// Filter by custom labels (e.g., user, environment)
{"where": [{"field": "labels.user_id", "operator": "==", "value": "123"}]}

架构格式

架构遵循 Firebase 基于路径的约定：

{
  "schemas": {
    "/organizations/{organizationId}": {
      "description": "Organization documents",
      "schema": {
        "type": "object",
        "required": ["id", "name"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" }
        }
      }
    },
    "/organizations/{organizationId}/products/{productId}": {
      "description": "Product catalog",
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "category": {
            "type": "string",
            "x-status": "legacy",
            "x-replacedBy": "productType"
          },
          "productType": {
            "type": "string",
            "x-status": "experimental"
          }
        }
      },
      "timestampFields": ["createdAt", "updatedAt"]
    }
  }
}

文档

• 安装指南
• @ 提及支持指南 - 如何使用 @firebase:firestore:// 引用
• 配置参考
• 架构创建指南
• 函数日志指南 - 使用类似 SQL 的语法、聚合和自定义标签查询 Cloud Functions 日志

许可证

MIT