MCP Firebase 服务器（模型上下文协议）

该服务器实现了模型上下文协议 (MCP)，充当 Claude 等大型语言模型 (LLM) 与 Firebase (Firestore) 之间的桥梁。它允许 LLM 通过将操作公开为 MCP“工具”来读取和写入 Firestore 集合。

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

先决条件

• Python 3.7+（最好是 3.8+，以便使用asynccontextmanager和 MCP 使用的完整类型提示功能）

• Pip（Python 包安装程序）或uv （MCP 文档推荐用于项目管理）

• 启用了 Firestore 的 Firebase 项目。

• Firebase 服务帐户密钥 JSON 文件。

Related MCP server: Firebase MCP

设置

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 ：

   python3 -m venv venv source venv/bin/activate # On macOS/Linux # venv\\Scripts\\activate # On Windows

   或者，如果使用uv （如 MCP 文档针对新项目所建议的那样）：

   uv venv source .venv/bin/activate # Or similar, depending on your uv setup

5. **安装依赖项：**使用pip ：

   pip install -r requirements.txt

   或者，如果使用uv ：

   uv pip install -r requirements.txt

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

运行服务器

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

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

   首先，使脚本可执行：

   chmod +x run_server.sh

   然后，使用脚本运行服务器：

   ./run_server.sh

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

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

   mcp dev mcp_firebase_server.py

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

MCP 工具曝光

该服务器名为MCPFirebaseServer ，公开以下工具：

1. query_firestore_collection

• **描述（来自文档字符串）：**从指定的 Firestore 集合中检索文档。

• 参数：

  • collection_name （字符串，必需）：要查询的 Firestore 集合的名称。

  • limit （整数，可选，默认值：50）：要返回的最大文档数。

• 返回： (List[Dict[str, Any]]) 集合中的文档列表。每个文档都是一个包含id字段的字典。如果发生错误（例如， [{"error": "Firestore not initialized..."}]或[{"error": "Failed to query..."}] ），则返回一个包含单个错误字典的列表。

2. add_document_to_firestore

• **描述（来自文档字符串）：**将具有自动生成的 ID 的新文档添加到指定的 Firestore 集合。

• 参数：

  • collection_name （字符串，必需）：将添加文档的 Firestore 集合的名称。

  • document_data （对象/字典，必需）：表示要添加的文档的字典。

• 返回： (Dict[str, Any]) 一个字典，包含success （布尔值）以及成功时的id （字符串）和message （字符串），或失败时的error （字符串）。成功示例： {"success": True, "id": "newDocId", "message": "Document added to 'logs'"}失败示例： {"success": False, "error": "Firestore not initialized..."}

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

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

一般集成步骤：

1. **服务器可用性：**确保mcp_firebase_server.py及其依赖项（包括serviceAccountKey.json ）在 MCP 客户端将运行或可以启动进程的系统上可访问。

2. **客户端配置：**需要配置 MCP 客户端应用程序以了解如何启动MCPFirebaseServer 。此配置通常涉及指定以下内容：

   • 要执行的命令（例如， python或uv run python ）。

   • 该命令的参数（例如mcp_firebase_server.py的路径）。

   • 可选地，服务器可能需要的任何环境变量（尽管我们当前的服务器需要同一目录中的serviceAccountKey.json ，但密钥路径的环境变量可以作为替代方案）。

3. 启动和沟通：

   • 当 MCP 客户端需要使用该服务器提供的工具时，它将使用配置的命令启动mcp_firebase_server.py 。

   • 然后，客户端和服务器通过 MCP 协议（例如，通过stdio ）进行通信。客户端可以发现可用的工具（ query_firestore_collection 、 add_document_to_firestore ）并调用它们。

概念配置示例（针对 Claude Desktop 等 MCP 客户端）：

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

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

配置要点：

• "command" ：要运行的可执行文件（例如python ）。确保它位于系统的 PATH 中，或者提供 Python 解释器的完整路径。

• "args" ：参数列表。第一个参数通常是要执行的脚本。**务必使用mcp_firebase_server.py的完整绝对路径，**以确保客户端能够找到它，无论客户端本身从何处启动。

• "cwd" ：有时，您可能需要为服务器进程指定工作目录，特别是如果它依赖于其他文件的相对路径（尽管我们的serviceAccountKey.json路径相对于脚本本身，如果脚本路径是绝对的，则通常是健壮的）。

• "env" ：用于传递环境变量。虽然我们当前的服务器是相对于自身路径来定位serviceAccountKey.json的，但对于配置更高的服务器来说，一种常见的模式是通过环境变量传递凭证路径或其他设置。

交互流程（回顾）：

1. 客户端启动服务器： MCP 客户端（使用上述配置）启动mcp_firebase_server.py 。

2. **服务器初始化：**我们的服务器尝试连接到 Firebase。

3. **工具发现和调用：**客户端根据需要发现并调用query_firestore_collection或add_document_to_firestore等工具。

4. **服务器响应：**结果通过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 检查器的服务器。这样您就可以查看已发现的工具并以交互方式进行测试。

• 确保serviceAccountKey.json已正确放置，或者在 MCP 客户端启动服务器时已设置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 )。