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: FireConfigMCP

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

Предпосылки

Проект 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