AI导哈

Firestore MCP 服务器

一个将Firestore数据库暴露为一组只读工具的MCP（模型上下文协议）服务器，支持多种传输方式（可流式HTTP、SSE、STDIO），适用于本地、传统服务器或无服务器环境。

  • by CPEL-SAC
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 CPEL-SAC/firestore-mcp-server

使用说明

Firestore MCP 服务器

一个MCP（模型上下文协议）服务器，它将Firestore数据库作为一组只读工具进行暴露。该项目提供了三种传输方式（可流式传输的HTTP、SSE、STDIO），因此可以在本地、传统服务器或无服务器环境中（如Vercel）运行。

亮点

  • 能够识别Firestore的工具，用于列出集合、检查采样模式以及运行过滤/聚合查询
  • 为 Firestore 原语（时间戳、GeoPoint、引用）提供安全的序列化方法，以避免 JSON 错误
  • 在STDIO、可流式HTTP和SSE传输中共享的干净MCP服务器引导程序
  • 用于开发的即用型脚本（npm run dev*) 和生产 (npm start， npm run start:*)
  • 与Codex CLI、Claude CLI、Gemini CLI或任何MCP兼容的客户端配合使用

先决条件

  1. Node.js 18及以上版本 （或您的托管服务提供商所需的运行时）
  2. Firebase服务帐户JSON文件 具有Firestore访问权限
  3. 环境变量 FIREBASE_SERVICE_ACCOUNT 包含JSON字符串（单行或转义）

.env 示例：

FIREBASE_SERVICE_ACCOUNT='{"type":"service_account","project_id":"your-project",...}'
PORT=3000

安装并运行

npm install

# Streamable HTTP (recommended for remote/serverless)
npm run dev        # hot reload via tsx
npm start          # production build (uses dist/mcp-streamable-server.js)

# SSE HTTP (legacy long-lived connections)
npm run dev:sse
npm run start:sse

# STDIO (local CLI integrations)
npm run dev:stdio
npm run start:stdio

# Build TypeScript -> dist/
npm run build

运输方式

可流式传输的HTTP（推荐）

  • 文件： src/mcp-streamable-server.ts
  • 终点：
    • GET /health – 就绪性探针
    • GET|POST|DELETE /mcp – 由……处理/负责 StreamableHTTPServerTransport
  • 默认无状态，可部署到 Vercel、Netlify、Cloudflare 等平台。

服务器发送事件（旧版）

  • 文件： src/mcp-http-server.ts
  • 工作流程：
    • GET /mcp 打开SSE流并返回会话ID
    • POST /mcp?sessionId=... 发送JSON-RPC消息
    • DELETE /mcp?sessionId=... 结束会议
  • 适用于如铁路或渲染等保持连接开放的平台。

STDIO（仅限本地）

  • 文件： src/index.ts
  • 通过标准输入输出暴露相同的工具集；非常适合本地命令行界面使用或测试。

MCP 工具

工具 目的 备注
list_collections 列出所有顶级集合。 返回一个以换行符分隔的列表。
inspect_collection_schema 示例文档（默认10个）和报告字段类型及示例。 支持嵌套对象；Firestore特殊类型可安全序列化。
query_firestore 运行过滤、排序、限制和聚合操作。 聚合操作（sum， avg忽略非数值条目，响应报告中会显示被忽略的条目数量。

示例 query_firestore 呼叫；打电话

{
  "name": "query_firestore",
  "arguments": {
    "collectionPath": "users",
    "filters": [
      {"field": "age", "operator": ">=", "value": 18}
    ],
    "orderBy": [
      {"field": "createdAt", "direction": "desc"}
    ],
    "limit": 10,
    "aggregation": {
      "count": true,
      "sum": "points",
      "avg": "score"
    }
  }
}

连接MCP客户端

Codex CLI（STDIO）

{
  "mcpServers": {
    "firestore": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "FIREBASE_SERVICE_ACCOUNT": "<service-account-json>"
      }
    }
  }
}

Codex/Claude/Gemini 命令行界面（远程流式可传输HTTP）

将客户端指向已部署的终端，并进行设置 transport 到；给；对于；为了 streamable-http：

{
  "mcpServers": {
    "firestore": {
      "url": "https://your-app.example.com/mcp",
      "transport": "streamable-http"
    }
  }
}

笔记

  • 该服务器为只读模式；如需执行数据修改操作，必须单独实现。
  • FIREBASE_SERVICE_ACCOUNT 必须保持私密——请在您的托管控制面板或密钥管理器中进行配置。

部署

Vercel（可流式传输的HTTP）

  1. npm i -g vercel
  2. vercel login
  3. vercel env add FIREBASE_SERVICE_ACCOUNT
  4. npm run build
  5. vercel --prod

渲染（可流式传输的HTTP）

  • 使用蓝图 render.yaml 或手动配置它：
    • 构建命令： npm run build
    • 启动命令： npm start
    • 必需的环境变量： FIREBASE_SERVICE_ACCOUNT

铁路（SSE 或 Streamable）

  • 构建命令： npm run build
  • 启动命令： npm start （可流式传输）o npm run start:sse 上海证券交易所
  • 环境变量： FIREBASE_SERVICE_ACCOUNT

API 概述

  • GET / – 服务元数据
  • GET /health – 健康检查
  • 可流式传输的HTTP： GET|POST|DELETE /mcp
  • 上海证券交易所 GET /mcp， POST /mcp?sessionId=...， DELETE /mcp?sessionId=...

故障排除

  • 缺少凭据确保 FIREBASE_SERVICE_ACCOUNT 是一个定义正确且有效的JSON。
  • 非数值聚合结果响应中指示了有多少文档被忽略。
  • 会话错误对于SSE（服务器发送事件），包括 sessionId 查询参数；对于可流式传输的HTTP，请确保客户端发送 Mcp-Session-Id 在需要时添加标题。
  • **CORS（跨源资源共享）**默认情况下启用了开放的CORS（跨源资源共享）；如果您控制客户端来源，请进行收紧设置。

许可证

MIT——参见 LICENSE 详情请见。

相关 MCP