Firebase MCP

Логотип проекта

Тесты Firebase CI

Обзор

Firebase MCP позволяет помощникам на базе искусственного интеллекта работать напрямую со службами Firebase, включая:

Firestore : Операции с базой данных документов
Хранилище : управление файлами с надежными возможностями загрузки
Аутентификация : управление пользователями и проверка

Сервер работает с клиентскими приложениями MCP, такими как Claude Desktop , Augment Code , VS Code и Cursor .

⚠️ Известная проблема : инструмент firestore_list_collections может возвращать ошибку проверки Zod в клиентских журналах. Это ошибочная ошибка проверки в MCP SDK, поскольку наше расследование подтвердило, что в ответе нет булевых значений. Несмотря на сообщение об ошибке, запрос по-прежнему работает правильно и возвращает правильные данные коллекции. Это ошибка уровня журнала, которая не влияет на функциональность.

Related MCP server: Firebase App Distribution API MCP Server

⚡ Быстрый старт

Предпосылки

Проект Firebase с учетными данными сервисной учетной записи
Среда Node.js

1. Установите MCP-сервер

Добавьте конфигурацию сервера в файл настроек MCP:

Рабочий стол Клода: ~/Library/Application Support/Claude/claude_desktop_config.json
Дополнение: ~/Library/Application Support/Code/User/settings.json
Курсор: [project root]/.cursor/mcp.json

MCP-серверы можно устанавливать вручную или во время выполнения через npx (рекомендуется). Способ установки определяет вашу конфигурацию:

Настроить для npx (рекомендуется)

{
  "firebase-mcp": {
    "command": "npx",
    "args": [
      "-y",
      "@gannonh/firebase-mcp"
    ],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/absolute/path/to/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"
    }
  }
}

Настроить для локальной установки

{
  "firebase-mcp": {
    "command": "node",
    "args": [
      "/absolute/path/to/firebase-mcp/dist/index.js"
    ],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/absolute/path/to/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"
    }
  }
}

2. Проверьте установку

Попросите своего клиента ИИ: «Пожалуйста, протестируйте все инструменты Firebase MCP».

🛠️ Настройка и конфигурирование

1. Конфигурация Firebase

Перейдите в Firebase Console → Настройки проекта → Учетные записи служб.
Нажмите «Сгенерировать новый закрытый ключ».
Сохраните файл JSON в надежном месте

2. Переменные среды

Необходимый

SERVICE_ACCOUNT_KEY_PATH : путь к ключу учетной записи службы Firebase в формате JSON (обязательно)

Необязательный

FIREBASE_STORAGE_BUCKET : Имя контейнера для Firebase Storage (по умолчанию [projectId].appspot.com )
MCP_TRANSPORT : тип используемого транспорта ( stdio или http ) (по умолчанию stdio )
MCP_HTTP_PORT : Порт для HTTP-транспорта (по умолчанию 3000 )
MCP_HTTP_HOST : Хост для HTTP-транспорта (по умолчанию localhost )
MCP_HTTP_PATH : Путь для HTTP-транспорта (по умолчанию /mcp )
DEBUG_LOG_FILE : Включить ведение журнала файлов:
- Установите значение true для записи в ~/.firebase-mcp/debug.log
- Укажите путь к файлу для записи журнала в пользовательское местоположение

3. Интеграция клиента

Клод Десктоп

Редактировать: ~/Library/Application Support/Claude/claude_desktop_config.json

VS Code / Дополнение

Редактировать: ~/Library/Application Support/Code/User/settings.json

Курсор

Редактировать: [project root]/.cursor/mcp.json

📚 API-ссылка

Инструменты для пожаротушения

Инструмент	Описание	Требуемые параметры
`firestore_add_document`	Добавить документ в коллекцию	`collection` `data`
`firestore_list_documents`	Список документов с фильтрацией	`collection`
`firestore_get_document`	Получить конкретный документ	`collection` , `id`
`firestore_update_document`	Обновить существующий документ	`collection` , `id` , `data`
`firestore_delete_document`	Удалить документ	`collection` , `id`
`firestore_list_collections`	Список корневых коллекций	Никто
`firestore_query_collection_group`	Запрос по подколлекциям	`collectionId`

Инструменты для хранения

Инструмент	Описание	Требуемые параметры
`storage_list_files`	Список файлов в каталоге	Нет (необязательно: `directoryPath` )
`storage_get_file_info`	Получить метаданные файла и URL	`filePath`
`storage_upload`	Загрузить файл из контента	`filePath` , `content`
`storage_upload_from_url`	Загрузить файл с URL	`filePath` , `url`

Инструменты аутентификации

Инструмент	Описание	Требуемые параметры
`auth_get_user`	Получить пользователя по ID или адресу электронной почты	`identifier`

💻 Руководство разработчика

Монтаж и строительство

git clone https://github.com/gannonh/firebase-mcp
cd firebase-mcp
npm install
npm run build

Проведение тестов

Сначала установите и запустите эмуляторы Firebase:

npm install -g firebase-tools
firebase init emulators
firebase emulators:start

Затем проведите тесты:

# Run tests with emulator
npm run test:emulator

# Run tests with coverage
npm run test:coverage:emulator

Структура проекта

src/
├── index.ts                  # Server entry point
├── utils/                    # Utility functions
└── lib/
    └── firebase/              # Firebase service clients
        ├── authClient.ts     # Authentication operations
        ├── firebaseConfig.ts   # Firebase configuration
        ├── firestoreClient.ts # Firestore operations
        └── storageClient.ts  # Storage operations

🌐 HTTP-транспорт

Firebase MCP теперь поддерживает HTTP-транспорт в дополнение к stdio-транспорту по умолчанию. Это позволяет запускать сервер как автономную HTTP-службу, к которой могут обращаться несколько клиентов.

Работает с HTTP-транспортом

Чтобы запустить сервер с HTTP-транспортом:

# Using environment variables
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 node dist/index.js

# Or with npx
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npx @gannonh/firebase-mcp

Конфигурация клиента для HTTP

При использовании HTTP-транспорта настройте клиент MCP для подключения к конечной точке HTTP:

{
  "firebase-mcp": {
    "url": "http://localhost:3000/mcp"
  }
}

Управление сеансом

HTTP-транспорт поддерживает управление сеансами, позволяя нескольким клиентам подключаться к одному и тому же экземпляру сервера. Каждый клиент получает уникальный идентификатор сеанса, который используется для поддержания состояния между запросами.

🔍 Устранение неполадок

Общие проблемы

Контейнер для хранения не найден

Если вы видите ошибку «Указанный контейнер не существует»:

Проверьте имя вашего контейнера в Firebase Console → Storage
Установите правильное имя контейнера в переменной среды FIREBASE_STORAGE_BUCKET

Инициализация Firebase не удалась

Если вы видите ошибку «Firebase не инициализирован»:

Проверьте правильность и полноту пути к ключу учетной записи службы.
Убедитесь, что учетная запись службы имеет необходимые разрешения для служб Firebase.

Требуется составной индекс

Если вы получили сообщение об ошибке «Для этого запроса требуется составной индекс»:

Найдите указанный URL в сообщении об ошибке.
Перейдите по ссылке, чтобы создать необходимый индекс в Firebase Console.
Повторите запрос после создания индекса (это может занять несколько минут)

Ошибка проверки Zod с `firestore_list_collections`

Если вы видите ошибку проверки Zod с сообщением «Ожидаемый объект, получено логическое значение» при использовании инструмента firestore_list_collections :

⚠️ Известная проблема : инструмент firestore_list_collections может возвращать ошибку проверки Zod в клиентских журналах. Это ошибочная ошибка проверки в MCP SDK, поскольку наше расследование подтвердило, что в ответе нет булевых значений. Несмотря на сообщение об ошибке, запрос по-прежнему работает правильно и возвращает правильные данные коллекции. Это ошибка уровня журнала, которая не влияет на функциональность.

Отладка

Включить ведение журнала файлов

Для диагностики проблем вы можете включить ведение журнала файлов:

# Log to default location (~/.firebase-mcp/debug.log)
DEBUG_LOG_FILE=true npx @gannonh/firebase-mcp

# Log to a custom location
DEBUG_LOG_FILE=/path/to/custom/debug.log npx @gannonh/firebase-mcp

Вы также можете включить ведение журнала в конфигурации клиента MCP:

{
  "firebase-mcp": {
    "command": "npx",
    "args": ["-y", "@gannonh/firebase-mcp"],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/path/to/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app",
      "DEBUG_LOG_FILE": "true"
    }
  }
}

Просмотр журнала в реальном времени

Для просмотра журналов в режиме реального времени:

# Using tail to follow the log file
tail -f ~/.firebase-mcp/debug.log

# Using a split terminal to capture stderr
npm start 2>&1 | tee logs.txt

Использование MCP-инспектора

MCP Inspector обеспечивает интерактивную отладку:

# Install MCP Inspector
npm install -g @mcp/inspector

# Connect to your MCP server
mcp-inspector --connect stdio --command "node ./dist/index.js"

📋 Форматирование ответа

Пример ответа на загрузку хранилища

{
  "name": "reports/quarterly.pdf",
  "size": "1024000",
  "contentType": "application/pdf",
  "updated": "2025-04-11T15:37:10.290Z",
  "downloadUrl": "https://storage.googleapis.com/bucket/reports/quarterly.pdf?alt=media",
  "bucket": "your-project.appspot.com"
}

Отображается пользователю как:

## File Successfully Uploaded! 📁

Your file has been uploaded to Firebase Storage:

**File Details:**
- **Name:** reports/quarterly.pdf
- **Size:** 1024000 bytes
- **Type:** application/pdf
- **Last Updated:** April 11, 2025 at 15:37:10 UTC

**[Click here to download your file](https://storage.googleapis.com/bucket/reports/quarterly.pdf?alt=media)**

🤝 Вклад

Форк репозитория
Создать ветку функций
Внедрение изменений с помощью тестов (требуется покрытие 80%+)
Отправить запрос на извлечение

📄 Лицензия

Лицензия MIT — подробности см. в файле LICENSE