Firestore MCP

🚀 Firestore MCP Server

Firestore MCP Server 是一个为 Firebase Firestore 打造的 Model Context Protocol (MCP) 服务器。借助该服务器，像 Claude 这样的 AI 助手能够直接与你的 Firestore 数据库进行交互。

🚀 快速开始

本服务器允许 AI 助手（如 Claude）直接与 Firebase Firestore 数据库交互。按照以下步骤进行安装和配置：

1. 克隆仓库
2. 安装依赖
3. 配置 Firebase 凭证
4. 构建项目
5. 配置 Claude Code
6. 重启 Claude Code 并批准 MCP 服务器

✨ 主要特性

• 全 CRUD 操作：支持文档的创建、读取、更新和删除。
• 集合管理：可列出集合和子集合。
• 查询支持：能使用 Firestore 查询运算符过滤文档。
• 文档计数：无需获取所有数据即可获取文档数量。
• 类型转换：自动处理 Firestore 类型（如 Timestamp、GeoPoint 等）。

📦 安装指南

1. 克隆仓库

git clone https://github.com/your-username/firestore-mcp.git
cd firestore-mcp

2. 安装依赖

npm install

3. 配置 Firebase 凭证

复制示例环境文件：

cp .env.example .env

在 .env 文件中编辑你的 Firebase 凭证：

FIREBASE_PROJECT_ID=your-project-id
FIREBASE_CLIENT_EMAIL=firebase-adminsdk-xxxxx@your-project.iam.gserviceaccount.com
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

获取 Firebase 凭证的方法

1. 访问 Firebase 控制台。
2. 选择你的项目。
3. 导航至 项目设置 > 服务账户。
4. 点击 生成新的私钥。
5. 下载 JSON 文件。
6. 将值复制到你的 .env 文件中：
   • project_id → FIREBASE_PROJECT_ID
   • client_email → FIREBASE_CLIENT_EMAIL
   • private_key → FIREBASE_PRIVATE_KEY

4. 构建项目

npm run build

💻 使用示例

基础用法

列出所有集合

Tool: list_collections

获取特定文档

Tool: get_document
Parameters:
  documentPath: "users/user123"

限制数量列出文档

Tool: list_documents
Parameters:
  collectionPath: "users"
  limit: 10

查询文档

Tool: query_documents
Parameters:
  collectionPath: "users"
  field: "status"
  operator: "=="
  value: "active"
  limit: 20

创建文档

Tool: create_document
Parameters:
  collectionPath: "users"
  data: {"name": "John Doe", "email": "john@example.com", "createdAt": "2024-01-01T00:00:00Z"}
  documentId: "user123"  # 可选，若未提供则自动生成

更新文档

Tool: update_document
Parameters:
  documentPath: "users/user123"
  data: {"name": "Jane Doe"}
  merge: true  # true = 与现有数据合并，false = 完全替换

删除文档

Tool: delete_document
Parameters:
  documentPath: "users/user123"

访问子集合

Tool: list_documents
Parameters:
  collectionPath: "users/user123/orders"
  limit: 10

📚 详细文档

Claude Code 配置

项目级配置（推荐）

在项目根目录创建 .mcp.json 文件：

{
  "mcpServers": {
    "firestore": {
      "command": "node",
      "args": ["/path/to/firestore-mcp/dist/index.js"]
    }
  }
}

⚠️ 重要提示

服务器会自动从其安装目录加载 .env 文件，因此不需要指定 cwd。

内联环境变量

如果你不想使用 .env 文件：

{
  "mcpServers": {
    "firestore": {
      "command": "node",
      "args": ["/path/to/firestore-mcp/dist/index.js"],
      "env": {
        "FIREBASE_PROJECT_ID": "your-project-id",
        "FIREBASE_CLIENT_EMAIL": "your-client-email",
        "FIREBASE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n"
      }
    }
  }
}

配置后操作

1. 重启 Claude Code。
2. 当提示时，批准 MCP 服务器。
3. Firestore 工具将在你的对话中可用。

可用工具

集合操作

文档操作

查询操作

支持的查询运算符

• == - 等于
• != - 不等于
• < - 小于
• <= - 小于等于
• > - 大于
• >= - 大于等于
• array-contains - 数组包含值
• in - 值在数组中
• array-contains-any - 数组包含任何值

配置选项

环境变量

调整行为

默认查询限制

list_documents 和 query_documents 的默认限制为 20。你可以通过指定 limit 参数在每个请求中覆盖此限制。

更新时的合并与替换

默认情况下，update_document 会将新数据与现有文档数据合并（merge: true）。将 merge: false 设置为替换整个文档。

安全注意事项

• 切勿提交 .env 文件 - 它们包含敏感凭证。
• 使用具有最小权限的服务账户 - 仅授予所需的 Firestore 访问权限。
• 开发时考虑使用只读服务账户 - 防止意外修改数据。
• 定期轮换凭证 - 定期生成新的服务账户密钥。

创建只读服务账户

1. 访问 Google Cloud 控制台。
2. 导航至 IAM & 管理 > 服务账户。
3. 创建新的服务账户。
4. 仅授予 Cloud Datastore 用户 角色（只读）。
5. 生成并下载密钥。

Firestore 数据类型

服务器会自动处理以下 Firestore 类型：

故障排除

“权限被拒绝” 错误

• 验证你的服务账户具有 Firestore 访问权限。
• 检查 FIREBASE_PROJECT_ID 是否与你的实际项目匹配。
• 确保私钥包含换行符 \n。

“无法加载默认凭证” 错误

• 验证所有三个环境变量是否都已设置。
• 检查 FIREBASE_PRIVATE_KEY 是否正确引用。

MCP 服务器未在 Claude 中显示

• 添加 .mcp.json 后重启 Claude Code。
• 检查配置中的文件路径是否正确。
• 验证构建是否成功完成（dist/index.js 存在）。

MCP 服务器显示 “失败” 状态

• 服务器会自动从其安装目录加载 .env 文件。
• 验证你的 .env 文件是否存在于 firestore-mcp 目录（而不是你的项目目录）中。
• 手动运行 node /path/to/firestore-mcp/dist/index.js 以查看错误消息。

开发

# 安装依赖
npm install

# 构建
npm run build

# 监听模式（更改时重新构建）
npm run dev

📄 许可证

本项目采用 MIT 许可证。

👥 贡献

欢迎贡献代码！请提交 issue 或 pull request。