MCP Firestore Db

MCP FirestoreDB-谷歌云Firestore MCP服务器

 ](https://www.npmjs.com/package/mcpfirestoredb) ](https://www.npmjs.com/package/mcpfirestoredb) ](https://nodejs.org/)      

全面的 模型上下文协议（MCP） 服务器 谷歌云火商店 数据库操作。该服务器通过MCP协议为文档数据库管理、收集操作和数据查询提供了12个强大的工具。

🚀 快速开始

先决条件

• Node.js 18+和npm
• 带有服务帐户凭据的Google Cloud Firestore数据库
• MCP兼容客户端（Claude Desktop、Cursor IDE等）

🎯 工具概述

可用工具（共17个）

此MCP服务器提供 17个优化工具 具有简短直观的名称，可实现高效的Firestore操作：

📝 文档操作（5个工具）：

• create_doc -创建新文档
• get_doc -检索特定文档
• get_docs -通过过滤查询多个文档
• update_doc -更新现有文档
• delete_doc -删除文档

🔄 批量操作（3个工具）：

• batch_create -一次创建多个文档
• batch_update -同时更新多个文档
• batch_delete -批量删除多个文档

📊 收集管理（4个工具）：

• list_collections -列出所有可用收藏
• collection_stats -获取详细的收款统计数据
• analyze_schema -分析文档模式和结构
• delete_collection -删除整个集合（小心）

🔍 指数管理（5个工具）：

• create_index -生成复合索引配置
• list_indexes -获取列出现有索引的指导
• get_index_status -检查索引构建状态和信息
• parse_index_error -解析Firestore错误消息以创建索引
• generate_indexes_config -生成firestore.indexes.json进行部署

🚀 关键能力

• 实时操作：直接访问Firestore数据库
• 高级查询：过滤、排序和分页支持
• 批处理：高性能批量操作
• 模式分析：智能文档结构分析
• 生产就绪：全面的错误处理和验证

⚙️ 配置

所需的环境变量

可选环境变量

安装选项

⭐ 选项1:NPM包（推荐）

最简单、最可靠的方法！ 无需安装或构建-只需配置和使用：

{
  "mcpServers": {
    "firestoredb": {
      "command": "npx",
      "args": ["-y", "mcpfirestoredb@1.1.2"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json",
        "FIREBASE_PROJECT_ID": "my-firebase-project",
        "FIRESTORE_DATABASE_ID": "(default)"
      }
    }
  }
}

优点：

• ✅ 始终使用最新的稳定版本
• ✅ 无需本地安装或编译
• ✅ 自动依赖关系管理
• ✅ 配置后立即工作
• ✅ 包括Bug修复（v1.1.1解决 __dirname 错误）

选项2:GitHub上的NPX

直接从GitHub使用开发版本：

{
  "mcpServers": {
    "firestoredb": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/MCPFirestoreDB"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json",
        "FIREBASE_PROJECT_ID": "my-firebase-project",
        "FIRESTORE_DATABASE_ID": "(default)"
      }
    }
  }
}

方案3：地方发展

git clone 
cd MCPFirestoreDB
npm install && npm run build

然后配置本地路径：

{
  "mcpServers": {
    "mcp-firestoredb": {
      "command": "node",
      "args": ["path/to/MCPFirestoreDB/dist/server.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json",
        "FIREBASE_PROJECT_ID": "your-project-id"
      }
    }
  }
}

🛠️ 可用工具

MCP FirestoreDB为Google Cloud Firestore运营提供了12个全面的工具：

CRUD操作

1. 📝 创建文档 - create_doc

在Firestore集合中创建新文档。

参数：

• collection_path：收款路径（例如，“用户”或“用户/123/订单”）
• document_id：可选文档ID（如果未提供，则自动生成）
• data：文档数据对象

2. 📖 获取文档 - get_doc

从集合中按ID检索特定文档。

参数：

• collection_path：收集路径
• document_id：要检索的文档ID

3. 📚 获取文档 - get_docs

使用可选的过滤和分页功能获取多个文档。

参数：

• collection_path：收集路径
• limit：最大文档数（默认值：100）
• order_by：订购字段
• order_direction：订单方向（“asc”或“desc”）
• where_conditions：where条件数组\[字段、运算符、值\]
• start_after：用于分页的文档ID

4. ✏️ 更新文档 - update_doc

更新集合中的现有文档。

参数：

• collection_path：收集路径
• document_id：要更新的文档ID
• data：要更新的数据（支持部分更新）
• merge：是否与现有数据合并（默认值：true）

5. 🗑️ 删除文档 - delete_doc

从集合中删除文档。

参数：

• collection_path：收集路径
• document_id：要删除的文档ID

批量操作

6. 📝📝 批量创建文档 - batch_create

在单个批处理操作中创建多个文档。

7. ✏️✏️ 批量更新文档 - batch_update

在单个批处理操作中更新多个文档。

8. 🗑️🗑️ 批量删除文档 - batch_delete

在一次批处理操作中删除多个文档。

收款操作

9. 📋 列出收藏 - list_collections

列出Firestore数据库中的所有集合。

参数：

• parent_path：子集合的可选父文档路径

10. 📊 获取收藏统计信息 - collection_stats

获取有关Firestore收藏的统计信息。

参数：

• collection_path：收集路径
• sample_size：要采样的文档数量（默认值：100）

11. 🏗️ 分析集合架构 - analyze_schema

分析集合中文档的模式。

参数：

• collection_path：收集路径
• sample_size：要采样的文档数量（默认值：100）

12. 🗑️📁 删除收藏 - delete_collection

删除整个收藏及其所有文档（小心使用）。

参数：

• collection_path：要删除的集合路径
• batch_size：每批要删除的文档（默认值：100）

📋 用法示例

文档操作

// Create a document
const newDoc = await create_doc({
  collection_path: "users",
  document_id: "user-123",
  data: {
    name: "John Doe",
    email: "john@example.com",
    createdAt: new Date()
  }
});

// Get a specific document
const document = await get_doc({
  collection_path: "users",
  document_id: "user-123"
});

// Update a document
const updated = await update_doc({
  collection_path: "users",
  document_id: "user-123",
  data: { lastLogin: new Date() },
  merge: true
});

查询数据

// Get documents with filtering
const activeUsers = await get_docs({
  collection_path: "users",
  where_conditions: [
    ["status", "==", "active"],
    ["createdAt", ">", "2024-01-01"]
  ],
  order_by: "createdAt",
  order_direction: "desc",
  limit: 50
});

// Get documents with pagination
const nextPage = await get_docs({
  collection_path: "users",
  limit: 10,
  start_after: "last-document-id"
});

批量操作

// Batch create multiple documents
const batchCreate = await batch_create({
  operations: [
    {
      collection_path: "products",
      document_id: "prod-1",
      data: { name: "Product 1", price: 100 }
    },
    {
      collection_path: "products",
      document_id: "prod-2",
      data: { name: "Product 2", price: 200 }
    }
  ]
});

采集分析

// List all collections
const collections = await list_collections();

// Get collection statistics
const stats = await collection_stats({
  collection_path: "users",
  sample_size: 1000
});

// Analyze collection schema
const schema = await analyze_schema({
  collection_path: "products",
  sample_size: 500
});

🔧 配置示例

生产环境：

{
  "mcpServers": {
    "firestoredb": {
      "command": "npx",
      "args": ["-y", "mcpfirestoredb@1.1.2"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/production-service-account.json",
        "FIREBASE_PROJECT_ID": "my-production-project",
        "FIRESTORE_DATABASE_ID": "(default)"
      }
    }
  }
}

使用Emulator进行开发：

{
  "mcpServers": {
    "firestoredb": {
      "command": "npx",
      "args": ["-y", "mcpfirestoredb@1.1.2"],
      "env": {
        "FIREBASE_PROJECT_ID": "demo-project",
        "FIRESTORE_EMULATOR_HOST": "localhost:8080",
        "DEBUG_FIRESTORE": "true"
      }
    }
  }
}

多个数据库：

{
  "mcpServers": {
    "firestoredb-main": {
      "command": "npx",
      "args": ["-y", "mcpfirestoredb@1.1.2"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json",
        "FIREBASE_PROJECT_ID": "my-project",
        "FIRESTORE_DATABASE_ID": "(default)"
      }
    },
    "firestoredb-analytics": {
      "command": "npx",
      "args": ["-y", "mcpfirestoredb@1.1.2"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json",
        "FIREBASE_PROJECT_ID": "my-project",
        "FIRESTORE_DATABASE_ID": "analytics-db"
      }
    }
  }
}

🚨 故障排除

身份验证问题：

• 未找到服务帐户：验证GOOGLE_APPLICATION_CREDENTIALS路径
• 权限不足：确保服务帐户具有Firestore权限
• 未找到项目：检查FIREBASE_PROJECT_ID是否与您的GCP项目匹配

连接问题：

• 仿真器连接失败：确保Firestore模拟器在指定端口上运行
• 网络超时：检查防火墙设置和网络连接
• 找不到数据库：验证FIRESTORE_DATABASE_ID是否存在

查询问题：

• where条件无效：检查字段名和运算符语法
• 查询超时：减少样本量或添加更具体的过滤器
• 需要索引：为复杂查询创建复合索引

Firestore模拟器设置：

1. 安装Firebase命令行界面： npm install -g firebase-tools
2. 启动模拟器： firebase emulators:start --only firestore
3. 设置FIRESTOR_EMULATOR_HOST环境变量
4. 使用演示项目ID进行测试

🔍 指数管理操作

Firestore索引管理工具可帮助您高效处理复合索引：

创建索引配置

// Generate index configuration for complex queries
{
  "collection_path": "users",
  "fields": [
    {"field": "status", "order": "ASCENDING"},
    {"field": "created_at", "order": "DESCENDING"}
  ]
}

解析索引时出错

// Parse Firestore error messages to extract index creation links
{
  "error_message": "The query requires an index. You can create it here: https://console.firebase.google.com/..."
}

指标状态监控

// Check index building progress
{
  "collection_path": "products",
  "index_fields": ["category", "price"]
}

重要提示：

• 由于安全限制，创建索引需要Firebase控制台或CLI
• 工具为手动创建提供配置生成和指导
• 监控索引构建状态以确保查询性能
• 使用 firestore.indexes.json 用于部署自动化

🧪 发展

npm install       # Install dependencies
npm run build     # Build project
npm test          # Run tests
npm start         # Development mode

🏗️ 建筑

项目结构：

src/
├── tools/                      # Tool implementations
│   ├── crudOperations.ts       # CRUD operations
│   ├── collectionOperations.ts # Collection management
│   ├── indexOperations.ts      # Index management operations
│   ├── types.ts                # Type definitions
│   └── index.ts                # Tool exports
├── db.ts                       # Firestore connection
├── server.ts                   # MCP server setup
└── tools.ts                    # Tool definitions

主要特点：

• ⚡ 高效的连接管理和优化的性能
• 🛡️ 全面的错误处理和验证
• 📊 高级收集统计和模式分析
• 🔧 基于环境的灵活配置
• 🚀 高性能批量操作
• 📋 具有详细见解的智能模式分析
• 🔍 具有过滤和分页功能的高级查询功能
• 🎯 缩短工具名称以提高可用性
• 🔄 实时数据库操作
• 📈 生产准备就绪，经过广泛测试

📝 重要说明

• 收集路径：对嵌套集合使用正斜杠（例如“users/123/orders”）
• 文档ID：如果创建操作中未提供，则自动生成
• 批量操作：每批仅限500次操作
• 安全规则：确保配置了正确的Firestore安全规则
• 索引：为复杂查询创建复合索引
• 成本：监控Firestore的使用情况以管理成本

🤝 贡献

1. 克隆该仓库
2. 创建特征分支(git checkout -b feature/name)
3. 进行更改并添加测试
4. 确保测试通过(npm test)
5. 提交更改(git commit -m 'Add feature')
6. 推送并打开拉取请求

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🏷️ 标签和关键字

数据库： firestore google-cloud-firestore nosql document-database database-analysis database-tools google-cloud database-management database-operations data-analysis

MCP&AI： model-context-protocol mcp-server mcp-tools ai-tools claude-desktop cursor-ide anthropic llm-integration ai-database intelligent-database

技术： typescript nodejs npm-package cli-tool database-client nosql-client database-sdk rest-api json-api database-connector

特征： collection-analysis document-operations batch-operations schema-analysis query-execution database-search data-exploration database-insights crud-operations real-time-database

使用案例： database-development data-science business-intelligence database-migration schema-documentation performance-analysis data-governance database-monitoring troubleshooting automation

🙏 致谢

• 模型上下文协议SDK
• @谷歌云/firestore
• 受启发于 MCPCosmosDB

🎯 MCP FirestoreDB通过模型上下文协议提供全面的Google Cloud Firestore数据库管理。非常适合与Firestore合作的开发人员和数据分析师！ 🚀