使用说明

项目简介

firestore-read MCP 服务器旨在解决在 ReactJS 应用开发中，LLM (如 Claude) 难以理解和操作 Firestore 数据库结构的问题。通过此服务器，开发者可以方便地让 LLM 直接访问 Firestore 数据库，获取最新的数据信息，从而减少 LLM 的“幻觉”并提高交互的准确性。

主要功能点

列出集合 (List collections): 获取 Firestore 数据库中所有集合的名称列表。
读取文档 (Get collection): 获取指定集合中的所有文档及其数据。
创建文档 (Create document): 在指定的集合中创建新的文档。
支持复杂数据类型: 能够处理 Firestore 中的时间戳 (timestamps) 和文档引用 (document references) 等复杂数据类型。

安装步骤

环境准备: 确保已安装 Python 3.11 或更高版本，并安装 'uv' 包管理器 (可以使用 'pip install uv' 安装)。

安装依赖: 在项目根目录下，使用 'uv' 安装所需的 Python 依赖库：

uv pip install firebase-admin
uv pip install python-dotenv

服务器配置

要将此 MCP 服务器配置到 MCP 客户端（例如 Claude Desktop），您需要编辑客户端的配置文件，通常是一个 JSON 文件。以下是针对 Claude Desktop 的配置示例，其他 MCP 客户端的配置方式可能类似。

Claude Desktop 配置 (claude_desktop_config.json):

请根据您的操作系统找到 'claude_desktop_config.json' 文件，通常位置如下：

MacOS: '~/Library/Application Support/Claude/claude_desktop_config.json'
Windows: '%APPDATA%/Claude/claude_desktop_config.json'

在该文件中，找到 '"mcpServers"' 部分（如果不存在则创建），并添加以下配置信息。请根据实际情况修改路径和凭据：

{
  "mcpServers": {
    "firestore-read": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/firestore-read",  // 【请替换为您的 firestore-read 项目的绝对路径】
        "run",
        "src/firestore_read"             //  执行的模块路径，指向包含 main 函数的 __init__.py 文件
      ],
      "env": {
        "FIREBASE_API_KEY": "your-firebase-web-api-key",    // 【请替换为您的 Firebase Web API Key】
        "FIREBASE_PROJECT_ID": "your-firebase-project-id"  // 【请替换为您的 Firebase Project ID】
      }
    }
  }
}

配置参数说明:

'"firestore-read"': 服务器名称，在 Claude 中用于标识和调用此服务器。
'"command": "uv"': 启动服务器的命令，这里使用 'uv' 包管理器来运行 Python 模块。
'"args"': 传递给 'uv' 命令的参数列表：
- '"--directory"': 指定项目根目录，'【请替换为您的 firestore-read 项目的绝对路径】' 需要替换为实际的项目路径。
- '"run"': 'uv run' 命令用于运行指定的 Python 模块。
- '"src/firestore_read"': 指定要运行的 Python 模块，指向 'src/firestore_read/init.py' 文件，该文件包含了 'main' 函数。
'"env"': 设置服务器运行所需的环境变量：
- '"FIREBASE_API_KEY"': Firebase Web API Key，用于初始化 Firebase 客户端，'【请替换为您的 Firebase Web API Key】' 需要替换为您的 Firebase Web API Key。
- '"FIREBASE_PROJECT_ID"': Firebase Project ID，用于指定 Firebase 项目，'【请替换为您的 Firebase Project ID】' 需要替换为您的 Firebase Project ID。

重要提示:

确保您已在 Firebase 控制台中创建项目，并获取了 Web API Key 和 Project ID。
路径配置: '"--directory"' 参数中的路径必须是您 'firestore-read' 项目在您本地文件系统中的绝对路径。请根据您的实际项目存放位置进行修改。
环境变量: 'FIREBASE_API_KEY' 和 'FIREBASE_PROJECT_ID' 是连接 Firebase 的凭据，请确保配置正确。虽然文档指出 Web API Key 可以安全地暴露在客户端代码中，但仍建议您妥善保管，避免泄露。

基本使用方法

配置完成后，您可以在 Claude 等 MCP 客户端中通过自然语言指令来调用此服务器的功能。以下是一些示例：

列出集合: 在 Claude 中输入类似 "列出所有 Firestore 集合" 或 "有哪些数据库集合" 的指令。Claude 应该能够调用 'list-collections' 工具并返回集合列表。
读取文档: 输入类似 "显示 users 集合中的文档" 或 "读取 products 集合的数据" 的指令。Claude 会调用 'get-collection' 工具并返回指定集合的文档数据。
创建文档: 输入类似 "创建一个新的 test 文档，数据为 {name: 'example', value: 123}" 或 "在 items 集合中添加一个文档，内容是 {title: 'New Item'}" 的指令。Claude 将调用 'create-document' 工具并在指定集合中创建新文档。

请注意，具体的指令格式可能取决于您使用的 MCP 客户端的自然语言理解能力。您可以参考仓库的 'Usage Examples' 部分获取更多示例。

关键词