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。