MCP Firebase 服务器 (模型上下文协议)

该服务器实现了模型上下文协议 (MCP)，作为像 Claude 这样的大型语言模型 (LLM) 和 Firebase (Firestore) 之间的桥梁。它通过将这些操作暴露为 MCP "工具"，允许 LLM 读取和写入 Firestore 集合。

该服务器使用官方的 mcp Python SDK 构建。

前提条件

• Python 3.7+（建议使用 3.8+ 以支持 asynccontextmanager 和 MCP 使用的完整类型提示功能）
• Pip（Python 包安装器）或 uv（MCP 文档推荐用于项目管理）
• 启用了 Firestore 的 Firebase 项目。
• Firebase 服务帐户密钥 JSON 文件。

设置

1. 克隆/下载：
   确保在本地目录中拥有服务器文件 (mcp_firebase_server.py)、requirements.txt 等。

2. 服务帐户密钥：

   • 服务器需要 Firebase 服务帐户密钥进行身份验证。
   • 选项 1（推荐用于 MCP 客户端配置）： 将 SERVICE_ACCOUNT_KEY_PATH 环境变量设置为您的服务帐户 JSON 文件的绝对路径。当服务器由 MCP 客户端启动时，这是最灵活的方法。
   • 选项 2（备用）： 如果未设置 SERVICE_ACCOUNT_KEY_PATH 环境变量，服务器将在其自身目录（与 mcp_firebase_server.py 相同的目录）中查找名为 serviceAccountKey.json 的文件。如果使用此方法，请相应地重命名您的密钥文件。
   • 重要提示： 确保您的服务帐户密钥文件（无论其名称或访问方式如何）保持安全，并且如果项目中有本地副本，则最好将其列入 .gitignore。

3. Firebase 存储桶（可选）：

   • 如果您打算在此服务器上使用 Firebase 存储功能（目前没有工具使用它，但可以添加），请将 FIREBASE_STORAGE_BUCKET 环境变量设置为您的 Firebase 项目的存储桶名称（例如，your-project-id.appspot.com）。如果设置了此值，服务器将读取并打印它。

4. 创建虚拟环境（推荐）：
   使用 venv：
   bash
   python3 -m venv venv
   source venv/bin/activate # 在 macOS/Linux 上

   venv\Scripts\activate # 在 Windows 上

   或者，如果使用 uv（如 MCP 文档对新项目所建议）：
   bash
   uv venv
   source .venv/bin/activate # 或根据您的 uv 设置类似的操作

5. 安装依赖项：
   使用 pip：
   bash
   pip install -r requirements.txt

   或者，如果使用 uv：
   bash
   uv pip install -r requirements.txt

   这将安装 mcp[cli] 和 firebase-admin。

运行服务器

有几种方法可以运行这个 MCP 服务器：

1. 直接执行（通过 run_server.sh 进行 stdio 传输）：
   提供了一个 run_server.sh 脚本来简化服务器的启动。此脚本会在运行 Python 脚本之前激活虚拟环境（如果命名为 venv 并存在于项目根目录中）。

   首先，使脚本可执行：
   bash
   chmod +x run_server.sh

   然后，使用脚本运行服务器：
   bash
   ./run_server.sh

   这是 MCP 客户端通常配置来启动服务器的方式（参见下面的“与 Claude 一起使用”部分）。

2. 使用 MCP CLI 进行开发和检查 (mcp dev)：
   mcp CLI（作为 mcp[cli] 的一部分安装）提供了一个开发服务器和检查工具。在开发过程中强烈推荐使用。
   bash
   mcp dev mcp_firebase_server.py

   这将启动服务器，并通常会提供一个 Web 界面来检查其功能（工具、资源）并进行测试调用。

暴露的 MCP 工具

该服务器名为 MCPFirebaseServer，暴露了以下工具：

1. mcp_firebase_query_firestore_collection

• 描述（来自文档字符串）： 从指定的 Firestore 集合中检索文档。
• 参数：* collection_name (字符串，必填)：要查询的Firestore集合的名称。
• limit (整数，可选，默认值：50)：返回的最大文档数量。
• 返回值： 从集合中获取的文档列表，或错误信息。

2. mcp_firebase_add_document_to_firestore

• 描述（来自docstring）： 向指定的Firestore集合添加一个具有自动生成ID的新文档。
• 参数：
  • collection_name (字符串，必填)：将要添加文档的Firestore集合的名称。
  • document_data (对象/字典，必填)：表示要添加的文档的字典。
• 返回值： 包含成功状态和新文档ID的字典，或错误信息。

3. mcp_firebase_list_firestore_collections

• 描述（来自docstring）： 列出Firestore数据库中的所有顶级集合。
• 参数：
  • random_string (字符串，必填)：一个虚拟参数（可以是任何字符串），因为此工具不接受有意义的输入。
• 返回值： 字典列表，每个字典包含一个集合的id，或错误信息。

4. mcp_firebase_get_firestore_document

• 描述（来自docstring）： 根据ID从Firestore集合中检索特定文档。
• 参数：
  • collection_name (字符串，必填)：Firestore集合的名称。
  • document_id (字符串，必填)：要检索的文档的ID。
• 返回值： 表示文档数据的字典，或错误信息。

5. mcp_firebase_list_document_subcollections

• 描述（来自docstring）： 列出Firestore中指定文档的所有子集合。
• 参数：
  • collection_name (字符串，必填)：父集合的名称。
  • document_id (字符串，必填)：其子集合需要被列出的文档的ID。
• 返回值： 字典列表，每个字典包含一个子集合的id，或错误信息。

6. mcp_firebase_update_firestore_document

• 描述（来自docstring）： 更新指定Firestore集合中的现有文档。
• 参数：
  • collection_name (字符串，必填)：Firestore集合的名称。
  • document_id (字符串，必填)：要更新的文档的ID。
  • update_data (对象/字典，必填)：包含要更新字段的字典。
• 返回值： 包含成功状态的字典，或错误信息。

7. mcp_firebase_query_firestore_collection_with_filter

• 描述（来自docstring）： 通过字段值（仅支持相等==操作符）过滤来从指定的Firestore集合检索文档。
• 参数：
  • collection_name (字符串，必填)：要查询的Firestore集合的名称。
  • filters (对象/字典，必填)：键为字段名、值为用于过滤的值的字典（例如，{"category": "electronics", "available": True}）。
  • limit (整数，可选，默认值：50)：返回的最大文档数量。
• 返回值： 符合过滤条件的集合中文档列表，或错误信息。

与Claude（或其他MCP客户端）一起使用

此MCP Firebase服务器设计为作为单独进程运行，通常由MCP客户端应用程序（如Claude桌面版或使用Windsurf等平台构建的能够管理MCP服务器的自定义应用程序）启动。然后客户端与此服务器通信，对于本地运行的服务器通常通过stdio（标准输入/输出）进行。

一般集成步骤：

1. 服务器可用性： 确保mcp_firebase_server.py及其依赖项（包括serviceAccountKey.json）在MCP客户端将运行或可以启动进程的系统上可访问。2. 客户端配置： MCP 客户端应用程序需要进行配置，以便知道如何启动您的 MCPFirebaseServer。此配置通常包括指定：

   • 要执行的 命令（例如，python 或 uv run python）。
   • 该命令的 参数（例如，指向 mcp_firebase_server.py 的路径）。
   • 可选地，服务器可能需要的任何 环境变量（尽管我们当前的服务器期望 serviceAccountKey.json 位于同一目录中，但可以通过环境变量来指定密钥路径作为替代方案）。

2. 启动和通信：

   • 当 MCP 客户端需要使用此服务器提供的工具时，它将使用已配置的命令启动 mcp_firebase_server.py。
   • 然后，客户端和服务器通过 MCP 协议（例如，通过 stdio）进行通信。客户端可以发现可用的工具（如 mcp_firebase_query_firestore_collection、mcp_firebase_add_document_to_firestore 等）并调用它们。

概念性配置示例（针对类似 Claude Desktop 的 MCP 客户端）：

许多与 MCP 兼容的客户端应用程序（如 Claude Desktop，在 MCP 文档中有提及）使用配置文件（通常是 JSON 格式）来定义如何启动和管理 MCP 服务器。虽然具体格式可能因客户端而异，但原理是相似的。

以下是一个基于 MCP 文档中常见模式的 概念性 示例。您需要根据所选择的 MCP 客户端（Claude Desktop、Windsurf 等）的具体配置机制进行调整。

json
{
"mcpServers": {
"firebase": { // 您在客户端配置中为此服务器实例分配的唯一名称
"command": "/full/path/to/your/mc-firebase-server/run_server.sh", // 重要：使用脚本的绝对路径
"args": [], // 如果 run_server.sh 处理所有内容，则通常为空
// "cwd": "/full/path/to/your/mc-firebase-server/", // 如果 run_server.sh 切换到其自己的目录，则通常不需要
"env": {
// 替换为您的服务帐户密钥文件的实际绝对路径
"SERVICE_ACCOUNT_KEY_PATH": "/path/to/your/serviceAccountKey.json",
// 可选：如果将来需要的工具需要 Firebase 存储桶名称，请替换为您实际的 Firebase 存储桶名称
"FIREBASE_STORAGE_BUCKET": "your-project-id.appspot.com"
}
}
}
}

配置的关键点：

• "command"：要运行的可执行文件（例如，python）。确保它在系统的 PATH 中，或者提供 Python 解释器的完整路径。
• "args"：参数列表。第一个参数通常是待执行的脚本。务必使用 mcp_firebase_server.py 的完整绝对路径，以确保无论客户端从何处启动，都能找到该脚本。
• "cwd"（当前工作目录）：有时，您可能需要指定服务器进程的工作目录，特别是当它依赖于其他文件的相对路径时（尽管我们的 serviceAccountKey.json 路径相对于脚本本身，这通常在脚本路径为绝对路径时是健壮的）。
• "env"：用于传递环境变量。虽然我们当前的服务器会查找相对于其自身路径的 serviceAccountKey.json，但对于更可配置的服务器来说，通过环境变量传递凭据路径或其他设置是一种常见模式。SERVICE_ACCOUNT_KEY_PATH 对于身份验证至关重要。FIREBASE_STORAGE_BUCKET 是可选的，并且目前由所提供的工具未使用，但如果以后添加了存储相关的工具，则可能会变得相关。

交互流程（回顾）：

1. 客户端启动服务器： MCP 客户端（使用上述配置）启动 mcp_firebase_server.py。
2. 服务器初始化： 我们的服务器尝试连接到 Firebase。
3. 工具发现与调用： 客户端按需发现并调用诸如 mcp_firebase_query_firestore_collection 或 mcp_firebase_add_document_to_firestore 等工具。服务器响应： 结果通过 stdio 发送回客户端。

针对 Claude Desktop 或 Windsurf 的具体说明：

• Claude Desktop： 如果您使用的是 Claude Desktop，请参考其文档，了解如何添加和配置自定义 MCP 服务器。上面的 JSON 结构是一种常见的模式，您可以根据需要进行调整。
• Windsurf： 如果您的编排器是 Windsurf 并且它支持管理 MCP 服务器，那么它将有自己定义和启动这些外部工具服务器的方法。您需要查阅 Windsurf 的文档以获取具体信息，但核心信息（命令、运行 mcp_firebase_server.py 的参数）将是相同的。

如果您的客户端没有专门的 MCP 服务器管理 UI/配置文件，但可以执行 shell 命令并通过 stdio 进行交互，您可以编程方式启动 mcp_firebase_server.py 脚本，然后使用 MCP 客户端库（如 mcp.client.stdio 中的库）与其通信。

开发与测试

• 使用 mcp dev mcp_firebase_server.py 命令在 MCP Inspector 下运行服务器。这允许您查看发现的工具并进行交互式测试。
• 确保在 MCP 客户端启动服务器时正确放置了 serviceAccountKey.json 文件或设置了 SERVICE_ACCOUNT_KEY_PATH 环境变量。
• 检查服务器的控制台输出，查看 Firebase 初始化消息和任何运行时错误。

run_server.sh 脚本：

项目根目录中的 run_server.sh 脚本设计用于：

1. 确定其自身的位置并将当前目录更改为该位置。
2. 如果项目根目录中存在名为 venv 的 Python 虚拟环境，则定位并激活该环境。
3. 使用 python 解释器（理想情况下是从已激活的 venv 中）执行 mcp_firebase_server.py 脚本。

此脚本确保 MCP 服务器在其预期环境中运行。请记得使其可执行（chmod +x run_server.sh）。