Firebase Basics

Prerequisites

Complete these setup steps before proceeding:

1. Local Environment Setup: Verify the environment is properly set up so we can use Firebase tools:

• Run npx -y firebase-tools@latest --version to check if the Firebase CLI

is installed.

• Verify if the Firebase MCP server is installed using your existing tools.
• CRITICAL: Before configuring any extensions or agent environments

below, you MUST read references/local-env-setup.md.

• DO NOT SKIP this step: if 'firebase-basics' is the only Firebase skill

available to you, you must follow the reference for your agent environment to set up the full suite of Firebase skills:

• Gemini CLI: Review

references/setup/gemini_cli.md

• Antigravity: Review

references/setup/antigravity.md

• Android Studio: Review

references/setup/android_studio.md

• Claude Code: Review

references/setup/claude_code.md

• Cursor: Review

references/setup/cursor.md

• GitHub Copilot: Review

references/setup/github_copilot.md

• Other Agents: Review

references/setup/other_agents.md

1. Authentication: Ensure you are logged in to Firebase so that commands have the correct permissions. Run npx -y firebase-tools@latest login. For environments without a browser (e.g., remote shells), use npx -y firebase-tools@latest login --no-localhost.

• The command should output the current user.
• If you are not logged in, follow the interactive instructions from this

command to authenticate.

1. Active Project: Most Firebase tasks require an active project context.

[!IMPORTANT] For Agents: Before proceeding with project configuration,

you MUST pause and ask the developer if they prefer to:

>

1. Provide an existing Firebase Project ID, or

1. Create a new Firebase project.

• If using an existing Project ID:

1. Check the current project by running npx -y firebase-tools@latest use. 1. If the command outputs Active Project: <project-id>, confirm with the user if this is the intended project. 1. If not, or if no project is active, set the project provided by the user:

        npx -y firebase-tools@latest use <PROJECT_ID>

• If creating a new project: Run the following command to create it:

     npx -y firebase-tools@latest projects:create <project-id> --display-name "<display-name>"

Note: The `<project-id>` must be 6-30 characters, lowercase, and can contain digits and hyphens. It must be globally unique.

Firebase Usage Principles

Adhere to these principles:

1. Use npx for CLI commands: To ensure you always use the latest version of the Firebase CLI, always prepend commands with npx -y firebase-tools@latest instead of just firebase. For example, use npx -y firebase-tools@latest --version. NEVER suggest the naked firebase command as an alternative. 1. Prioritize official knowledge: For any Firebase-related knowledge, consult the developerknowledge_search_documents MCP tool before falling back to Google Search or your internal knowledge base. Including "Firebase" in your search query significantly improves relevance. 1. Follow Agent Skills for implementation guidance: Skills provide opinionated workflows (CUJs), security rules, and best practices. Always consult them to understand how to implement Firebase features correctly instead of relying on general knowledge. 1. Use Firebase MCP Server tools instead of direct API calls: Whenever you need to interact with remote Firebase APIs (such as fetching Crashlytics logs or executing Data Connect queries), use the tools provided by the Firebase MCP Server instead of attempting manual API calls. 1. Keep Plugin / Agent Skills updated: Since Firebase best practices evolve quickly, regularly check for and install updates to their Firebase plugin or Agent Skills. Similarly, if you encounter issues with outdated tools or commands, follow the steps below based on your agent environment:

• Antigravity: Follow

references/refresh/antigravity.md

• Gemini CLI: Follow

references/refresh/gemini-cli.md

• Claude Code: Follow

references/refresh/claude.md

• Cursor: Follow

references/refresh/other-agents.md

• Android Studio: Follow

references/refresh/android_studio.md

• Others: Follow

references/refresh/other-agents.md 1. Automate Config File Retrieval: When setting up iOS or Android apps, do NOT direct users to the Firebase Console to download google-services.json or GoogleService-Info.plist. Instead, use the Firebase CLI to fetch the config programmatically:

• For Android:

npx -y firebase-tools@latest apps:sdkconfig ANDROID <APP_ID> --project <PROJECT_ID>

• For iOS:

npx -y firebase-tools@latest apps:sdkconfig IOS <APP_ID> --project <PROJECT_ID> Save the output to the appropriate location (e.g., app/google-services.json for Android, or a path to be linked by xcode-project-setup for iOS).

References

• Initialize Firebase: See

references/firebase-service-init.md when you need to initialize new Firebase services using the CLI.

• Exploring Commands: See

references/firebase-cli-guide.md to discover and understand CLI functionality.

• SDK Setup: For detailed guides on adding Firebase to your app:
• Web: See references/web_setup.md
• Android: See references/android_setup.md
• iOS: See references/ios_setup.md

Common Issues

• Login Issues: If the browser fails to open during the login step, use

npx -y firebase-tools@latest login --no-localhost instead.

• Genkit: If using Genkit, install the skills:

  npx skills add genkit-ai/skills

🛠️ Firebase Android Setup Guide

______________________________________________________________________

📋 Prerequisites

Before running these commands, ensure you are authenticated: npx -y firebase-tools@latest login (or npx -y firebase-tools@latest login --no-localhost on remote servers)

0. Create an Android application

if you haven't already created an android application, create one.

1. Create a Firebase Project

If you haven't already created a project, create a new cloud project with a unique ID: npx -y firebase-tools@latest projects:create <UNIQUE_PROJECT_ID> --display-name '<DISPLAY_NAME>' Example: npx -y firebase-tools@latest projects:create my-cool-app-20260330 --display-name 'MyCoolApp'

2. Register Your Android App

Link your Android app module (package name) to your project. Notice that the display name is passed as a positional argument at the end: npx -y firebase-tools@latest apps:create ANDROID '<APP_DISPLAY_NAME>' --package-name '<PACKAGE_NAME>' --project <PROJECT_ID> Example: npx -y firebase-tools@latest apps:create ANDROID 'MyApplication' --package-name 'com.example.myapplication' --project my-cool-app-20260330

3. Download google-services.json

Fetch the configuration file using the App ID (which is printed in the output of the previous command): npx -y firebase-tools@latest apps:sdkconfig ANDROID <APP_ID> --project <PROJECT_ID> Example output extraction to file: # (Output must be saved as app/google-services.json)

✅ Verification Plan

Manual Verification

Validate that the project was created and registered successfully: npx -y firebase-tools@latest projects:list npx -y firebase-tools@latest apps:list --project <PROJECT_ID>

______________________________________________________________________

Exploring Commands

The Firebase CLI documents itself. Use help commands to discover functionality.

• Global Help: List all available commands and categories.

  npx -y firebase-tools@latest --help

• Command Help: Get detailed usage for a specific command.

  npx -y firebase-tools@latest [command] --help
  # Example:
  npx -y firebase-tools@latest deploy --help
  npx -y firebase-tools@latest firestore:indexes --help

Initialization

Before initializing, check if you are already in a Firebase project directory by looking for firebase.json.

1. Project Directory: Navigate to the root directory of the codebase. (Only if starting a completely new project from scratch without an existing codebase, create a directory first: `mkdir my-project && cd my-project`)

1. Initialize Services: Run the initialization command:

   npx -y firebase-tools@latest init

The CLI will guide you through:

• Selecting features (Firestore, Functions, Hosting, etc.).
• Associating with an existing project or creating a new one.
• Configuring files (e.g. firebase.json, .firebaserc).

Flutter & Firebase Setup Guide

This guide covers the initial setup of Flutter and its integration with Firebase using the FlutterFire CLI.

Prerequisites

1. Flutter SDK: Ensure Flutter is installed and available in the PATH.

Standard Setup (Manual):

1. Determine Architecture: Check if you are on Intel (x64) or Apple Silicon (arm64) using uname -m. 1. Download SDK: Fetch the latest stable SDK from the Flutter Archive. 1. Extract: Unzip the SDK to a permanent directory (e.g., ~/development/flutter). 1. Update PATH: Add the bin folder to your shell configuration (e.g., ~/.zshrc).

      echo 'export PATH="$PATH:$HOME/development/flutter/bin"' >> ~/.zshrc
      source ~/.zshrc

1. Verify: Run flutter doctor to ensure the SDK is correctly linked and initialized.

1. Firebase CLI: Ensure the Firebase CLI is available.

• Run npx -y firebase-tools@latest --version.
• Login with npx -y firebase-tools@latest login.

1. FlutterFire CLI: Install the official FlutterFire CLI globally.

• Run dart pub global activate flutterfire_cli.
• Note: Ensure ~/.pub-cache/bin is also in your PATH if flutterfire

is not found.

Step 1: Create a Flutter Project

If you don't have a project yet, create one:

flutter create my_awesome_app
cd my_awesome_app

Step 2: Configure Firebase

[!IMPORTANT] For Agents: Before running the configuration command, you

MUST pause and ask the developer if they prefer to:

>

1. Create a new Firebase project, or

1. Provide an existing Firebase Project ID.

• If the developer provides an existing Project ID, run:

  flutterfire configure --project=<project_id>

• If the developer prefers to create a new project interactively, run:

  flutterfire configure

This tool automates:

• Registering your apps (iOS, Android, Web, etc.) with a Firebase project.
• Generating the lib/firebase_options.dart file.

Step 3: Initialize Firebase in Code

Add the firebase_core package and initialize it in your main.dart.

1. Add the dependency:

flutter pub add firebase_core

2. Update lib/main.dart:

import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';
import 'firebase_options.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  runApp(const MyApp());
}

Step 4: Add Firebase Services

To add specific services (Firestore, Auth, etc.), follow the "Pub Add & Configure" pattern:

1. Add the service: flutter pub add cloud_firestore 1. Crucial: Re-run flutterfire configure to sync platform configurations. 1. Import and use the package in your code.

Step 5: Important Gotchas & Platform Specifics

1. Re-running flutterfire configure Upon Renaming

When creating a new project, developers often change the bundle identifier (iOS) or applicationId (Android) after the fact. If the package names change, flutterfire configure must be re-run to update the respective Google service files and firebase_options.dart.

2. Platform-Specific Build Requirements

• Android: Adding Firebase often requires a higher minSdkVersion (commonly

21 or 23) than the platform default. Be prepared to update android/app/build.gradle automatically when installing certain plugins.

• iOS: Always check if there is a Podfile in the /ios directory whenever

native services (like cloud_firestore) are added. If there is, run pod install. Failing to do this will cause Xcode build errors. Note that Flutter is moving towards Swift Package Manager (SPM), and FlutterFire supports SPM, so a Podfile may not exist if the project only uses SPM dependencies.

3. Web CORS Best Practices

When testing Firebase features locally on Chrome, requests to Google servers can sometimes get blocked by CORS policies. Avoid relying on --disable-web-security flags as it promotes bad security practices. Instead, run the app on localhost with a specific port, and ensure localhost is added to your Firebase Auth "Authorized Domains".

flutter run -d chrome --web-hostname=localhost --web-port=5000

4. Elaborating on WidgetsFlutterBinding.ensureInitialized()

In your main.dart, this call is mandatory before Firebase.initializeApp(). Why? Because Firebase initialization requires communication across Flutter's native iOS/Android method channels. ensureInitialized() guarantees the Fluter engine is fully booted up and ready to handle these native platform calls before runApp() executes.

Firebase iOS Setup Guide

⛔️ CRITICAL RULE: STATE MANAGEMENT (OBSERVATION VS COMBINE) ⛔️

When writing or updating SwiftUI code, you MUST prioritize the modern Swift Observation framework (`@Observable` macro and `@State`) as your default approach.

However, it is acceptable to use Combine (ObservableObject, @Published, @StateObject, @EnvironmentObject) under the following conditions:

• The user explicitly asks you to use Combine.
• There are strong signals in the existing codebase that the project is heavily

relying on Combine.

If neither of those conditions are true, default to the Swift 5.9+ Observation framework.

⛔️ CRITICAL RULE: INITIALIZATION ORDER ⛔️

When using SwiftUI, you MUST ensure FirebaseApp.configure() is called BEFORE any Firebase-dependent state objects are initialized.

• UNSAFE (CRASH): Declaring a @State (for @Observable) or @StateObject

(for Combine) property in the root App struct if its initializer touches Firebase. Property initializers run before the App.init() body, meaning the object's init() will fire before Firebase is configured.

• SAFE: Initialize Firebase in App.init() and pass your state objects into

the sub-views (like ContentView), or use onAppear for delayed setup.

Failing to follow this will result in a fatal crash: Default FirebaseApp is not configured.

1. Create a Firebase Project and App (Automated)

Do not use the Firebase Console. Use the CLI to automate setup:

1. Create the project: npx -y firebase-tools@latest projects:create 1. Action: Read the Xcode project (.pbxproj or Info.plist) to determine the iOS bundle ID. 1. Register the iOS app: npx -y firebase-tools@latest apps:create IOS <bundle-id> 1. Fetch the config: npx -y firebase-tools@latest apps:sdkconfig IOS <App-ID> 1. Save the output as GoogleService-Info.plist in your Xcode project folder. Ensure you remove any non-XML CLI output headers, and ensure the file is linked to the main application target.

2. Installation (Automated via Swift Package Manager CLI)

Do not use raw text parsing, sed, or Ruby scripts (like xcodeproj gem) to modify .pbxproj files directly.

Instead, use the `xcode-project-setup` skill. Load that skill using your tools to securely execute its native Swift package setup script. That skill handles installing the required SPM packages and safely linking the GoogleService-Info.plist file.

💡 TIP: ALWAYS USE THE LATEST SDK VERSION To ensure access to the latest

features and security fixes, always check for the most recent version of the

Firebase iOS SDK at

https://github.com/firebase/firebase-ios-sdk/releases

and use that version when adding the SPM dependency.

3. Initialization

Configure the shared FirebaseApp instance. You can do this either in a modern SwiftUI App structure or a traditional AppDelegate.

SwiftUI (Modern - SAFE PATTERN)

import SwiftUI
import FirebaseCore

@main
struct YourApp: App {
  // ⛔️ FATAL CRASH: @State private var auth = AuthManager()
  // property initializers run before init(), causing FirebaseApp not configured error
  @State private var authManager: AuthManager

  init() {
    // ✅ SAFE: This runs FIRST
    FirebaseApp.configure()
    
    // ✅ SAFE: Initialize state ONLY AFTER Firebase is configured
    _authManager = State(initialValue: AuthManager())
  }

  var body: some Scene {
    WindowGroup {
      ContentView()
        .environment(authManager)
    }
  }
}

AppDelegate (Traditional / UIKit)

import UIKit
import FirebaseCore

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ application: UIApplication,
                   didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    // ✅ SAFE: Always the first line in didFinishLaunching
    FirebaseApp.configure()
    return true
  }
}

Firebase Local Environment Setup

This skill documents the bare minimum setup required for a full Firebase experience for the agent. Before starting to use any Firebase features, you MUST verify that each of the following steps has been completed.

1. Verify Node.js

• Action: Run node --version.

• Handling: Ensure Node.js is installed and the version is >= 20. If

Node.js is missing or < v20, install it based on the operating system:

Recommended: Use a Node Version Manager This avoids permission issues when installing global packages.

For macOS or Linux:

1. Guide the user to the official nvm repository. 1. Request the user to manually install nvm and reply when finished. Stop and wait for the user's confirmation. 1. Make nvm available in the current terminal session by sourcing the appropriate profile:

     # For Bash
     source ~/.bash_profile
     source ~/.bashrc

     # For Zsh
     source ~/.zprofile
     source ~/.zshrc

1. Install Node.js:

     nvm install 24
     nvm use 24

For Windows:

1. Guide the user to download and install nvm-windows. 1. Request the user to manually install nvm-windows and Node.js, and reply when finished. Stop and wait for the user's confirmation. 1. After the user confirms, verify Node.js is available:

     node --version

Alternative: Official Installer

1. Guide the user to download and install the LTS version from nodejs.org. 1. Request the user to manually install Node.js and reply when finished. Stop and wait for the user's confirmation.

2. Verify Firebase CLI

• Command: npx -y firebase-tools@latest --version
• Expected: Successfully outputs a version string.

3. Verify Firebase Authentication

You must be authenticated to manage Firebase projects.

• Action: Run npx -y firebase-tools@latest login.
• Handling: If the environment is remote or restricted (no browser access),

run npx -y firebase-tools@latest login --no-localhost instead.

4. Install Agent Skills and MCP Server

To fully manage Firebase, the agent needs specific skills and the Firebase MCP server installed. Refer to the main SKILL.md for direct links to the installation instructions specific to your agent environment.

______________________________________________________________________

CRITICAL AGENT RULE: Do NOT proceed with any other Firebase tasks until EVERY step above has been successfully verified and completed.

Refresh Android Studio Local Environment

Follow these steps to refresh Gemini in Android Studio's local environment, ensuring that agent skills are fully up-to-date.

Gemini in Android Studio expects skills to be located at ~/.agents/skills.

1. List Available Skills: Identify all Firebase skills available in the repository:

   npx -y skills add firebase/agent-skills --list

1. Check Currently Installed Skills: Check the contents of the skills directory to see what is currently installed:

   ls -la ~/.agents/skills

1. Add Missing Skills: Use the skills CLI to add skills. If the CLI supports an android_studio agent identifier, you can run:

   npx -y skills add firebase/agent-skills --agent android_studio --skill "*" --yes

If the skills CLI does not support Android Studio directly, you can manually copy or symlink the desired skills from your local clone of firebase/agent-skills to ~/.agents/skills.

1. Update Existing Skills: To update skills, you can try:

   npx -y skills update --agent android_studio --yes

If manual installation was used, pull the latest changes from the firebase/agent-skills repository and copy the updated files to ~/.agents/skills.

Refresh Antigravity Local Environment

Follow these steps to refresh Antigravity's local environment, ensuring that their agent skills and plugins are fully up-to-date.

Antigravity relies on npx skills. Updates should prioritize the global level; if skills are installed at the project level, omit the --global flag.

1. List Available Skills: Identify all Firebase skills available in the repository:

   npx -y skills add firebase/agent-skills --list

1. Check Currently Installed Skills: Determine which skills are already installed and linked at both project and global levels:

   # Check project-level skills
   npx -y skills list --agent antigravity

   # Check global-level skills
   npx -y skills list --agent antigravity --global

Note: If a skill shows `Agents: not linked` in the output, it is installed but not currently available to Antigravity.

1. Add Missing or Unlinked Skills: Compare the results from Step 1 and Step 2\. For each missing or unlinked skill, follow the appropriate conditional instruction below:

• IF any Firebase skills were found at the PROJECT level in Step 2: Add

the missing skill to the project level:

     npx -y skills add firebase/agent-skills --agent antigravity --skill "<SKILL_NAME>" --yes

• IF any Firebase skills were found at the GLOBAL level in Step 2: Add

the missing skill to the global level:

     npx -y skills add firebase/agent-skills --agent antigravity --skill "<SKILL_NAME>" --global --yes

• IF NO Firebase skills were found in Step 2: Add each missing skill to

the global level:

     npx -y skills add firebase/agent-skills --agent antigravity --skill "<SKILL_NAME>" --global --yes

1. Update Existing Skills: Update all currently installed skills to their latest versions:

   # Update project-level skills
   npx -y skills update --agent antigravity --yes

   # Update global-level skills
   npx -y skills update --agent antigravity --global --yes

Refresh Claude Code Local Environment

Follow these steps to refresh Claude Code's local environment, ensuring that their agent skills and plugins are fully up-to-date.

Use Claude Code's native plugin manager instead of npx.

1. Update the Plugin: Run the specific CLI command to update the Firebase plugin:

   claude plugin update firebase@firebase

Refresh Gemini CLI Local Environment

Follow these steps to refresh Gemini CLI's local environment, ensuring that their agent skills and plugins are fully up-to-date.

Use the native Gemini CLI extension manager instead of npx.

1. Update the Extension: Run the specific CLI command to update:

   gemini extensions update firebase

Note: If the extension is named differently, replace `firebase` with the correct name from `gemini extensions list`.

Refresh Other Local Environment

Follow these steps to refresh the local environment of other agents, ensuring that their agent skills and plugins are fully up-to-date.

Other agents rely on npx skills. Updates should prioritize the global level; if skills are installed at the project level, omit the --global flag.

Replace <AGENT_NAME> with the actual agent name, which can be found in the skills repository README.

1. List Available Skills: Identify all Firebase skills available in the repository:

   npx -y skills add firebase/agent-skills --list

1. Check Currently Installed Skills: Determine which skills are already installed and linked for the agent at both project and global levels:

   # Check project-level skills
   npx -y skills list --agent <AGENT_NAME>

   # Check global-level skills
   npx -y skills list --agent <AGENT_NAME> --global

Note: If a skill shows `Agents: not linked` in the output, it is installed but not currently available to the agent.

1. Add Missing or Unlinked Skills: Compare the results from Step 1 and Step 2\. For each missing or unlinked skill, follow the appropriate conditional instruction below:

• IF any Firebase skills were found at the PROJECT level in Step 2: Add

the missing skill to the project level:

     npx -y skills add firebase/agent-skills --agent <AGENT_NAME> --skill "<SKILL_NAME>" --yes

• IF any Firebase skills were found at the GLOBAL level in Step 2: Add

the missing skill to the global level:

     npx -y skills add firebase/agent-skills --agent <AGENT_NAME> --skill "<SKILL_NAME>" --global --yes

• IF NO Firebase skills were found in Step 2: Add each missing skill to

the global level:

     npx -y skills add firebase/agent-skills --agent <AGENT_NAME> --skill "<SKILL_NAME>" --global --yes

1. Update Existing Skills: Update all currently installed skills to their latest versions:

   # Update project-level skills
   npx -y skills update --agent <AGENT_NAME> --yes

   # Update global-level skills
   npx -y skills update --agent <AGENT_NAME> --global --yes

Android Studio Setup

This guide explains how to set up Firebase agent skills for Gemini in Android Studio.

Skills Installation

Gemini in Android Studio expects skills to be located at ~/.agents/skills.

To install all Firebase skills, run the following command in your terminal:

npx -y skills add firebase/agent-skills --skill "*" --yes

Ensure that the skills are installed or linked to the ~/.agents/skills directory.

MCP Setup

MCP setup is currently skipped for Android Studio as it only supports SSE transport, while the Firebase CLI MCP server uses stdio. Direct integration is not supported without an SSE-to-stdio proxy.

Antigravity Setup

To get the most out of Firebase in Antigravity, follow these steps to install the agent skills and the MCP server.

1. Install and Verify Firebase Skills

Check if the skills are already installed before proceeding:

1. Check Local skills: Run ls -d .agent/skills/firebase-basics or ls -d .agents/skills/firebase-basics. If the directory exists, the skills are already installed locally. 1. Check Global skills: If not found locally, check the global installation by running:

   npx skills list --global --agent antigravity

If the output includes firebase-basics, the skills are already installed globally. 1. Install Skills: If both checks fail, run the following command to install the Firebase agent skills:

   npx skills add firebase/agent-skills --agent antigravity --skill "*"

Note: Omit `--yes` and `--global` to choose the installation location manually. If prompted interactively in the terminal, ensure you send the appropriate user choices via standard input to complete the installation. 1. Verify Installation: Re-run the checks in steps 1 or 2 to confirm that firebase-basics is now available.

2. Configure and Verify Firebase MCP Server

The MCP server allows Antigravity to interact directly with Firebase projects. This is considered the mandatory extension configuration required for full functionality.

1. Locate `mcp_config.json`: Find the configuration file for your operating system:

• macOS / Linux: ~/.gemini/antigravity/mcp_config.json
• Windows: %USERPROFILE%\\.gemini\\antigravity\\mcp_config.json

Note: If the `.gemini/antigravity/` directory or `mcp_config.json` file does not exist, create them and initialize the file with `{ "mcpServers": {} }` before proceeding.

1. Check Existing Configuration: Open mcp_config.json and check the mcpServers section for a firebase entry.

• It is already configured if the command is "firebase" OR if the

command is "npx" with "firebase-tools" and "mcp" in the args.

• Important: If a valid firebase entry is found, the MCP server is

already configured. Skip step 3 and proceed directly to step 4.

Example valid configurations:

   "firebase": {
     "command": "npx",
     "args": ["-y", "firebase-tools@latest", "mcp"]
   }

OR

   "firebase": {
     "command": "firebase",
     "args": ["mcp"]
   }

1. Add or Update Configuration: If the firebase block is missing or incorrect, add it to the mcpServers object:

   "firebase": {
     "command": "npx",
     "args": [
       "-y",
       "firebase-tools@latest",
       "mcp"
     ]
   }

CRITICAL: Merge this configuration into the existing `mcp_config.json` file. You MUST preserve any other existing servers inside the `mcpServers` object.

1. Verify Configuration: Save the file and confirm the firebase block is present and properly formatted JSON.

3. Restart and Verify Connection

1. Restart Antigravity: Instruct the user to restart the Antigravity application. Stop and wait for their confirmation before proceeding. 1. Confirm Connection: Check the MCP server list in the Antigravity UI to confirm that the Firebase MCP server is connected.

Claude Code Setup

To get the most out of Firebase in Claude Code, follow these steps to install the agent skills and the MCP server.

Recommended Method: Using Plugins

The recommended method is using the plugin marketplace to install both the agent skills and the MCP functionality.

1. Install and Verify Plugins

Check if the plugins are already installed before proceeding:

1. Check Existing Skills: Run npx skills list --agent claude-code to check for local skills. Run npx skills list --global --agent claude-code to check for global skills. Note whether the output includes firebase-basics. 1. Check Existing MCP Configuration: Run claude mcp list -s user and claude mcp list -s project. Note whether the output of either command includes firebase. 1. Determine Installation Path:

• If both skills and MCP configuration are found, the plugin is fully

installed. Stop here and skip all remaining setup steps in this document.

• If neither are found, proceed to step 4.
• If only one is found (e.g., skills are installed but MCP is missing, or

vice versa), stop and prompt the user. Explain the mixed state and ask if they want to proceed with installing the Firebase plugin before continuing to step 4. 1. Add Marketplace: Run the following command to add the marketplace (this uses the default User scope):

   claude plugin marketplace add firebase/agent-skills

1. Install Plugins: Run the following command to install the plugin:

   claude plugin install firebase@firebase

1. Verify Installation: Re-run the checks in steps 1 and 2 to confirm the skills and the MCP server are now available.

2. Restart and Verify Connection

1. Restart Claude Code: Instruct the user to restart Claude Code. Stop and wait for their confirmation before proceeding.

Cursor Setup

To get the most out of Firebase in Cursor, follow these steps to install the agent skills and the MCP server.

1. Install and Verify Firebase Skills

Check if the skills are already installed before proceeding:

1. Check Local skills: Run npx skills list --agent cursor. If the output includes firebase-basics, the skills are already installed locally. 1. Check Global skills: If not found locally, check the global installation by running:

   npx skills list --global --agent cursor

If the output includes firebase-basics, the skills are already installed globally. 1. Install Skills: If both checks fail, run the following command to install the Firebase agent skills:

   npx skills add firebase/agent-skills --agent cursor --skill "*"

Note: Omit `--yes` and `--global` to choose the installation location manually. If prompted interactively in the terminal, ensure you send the appropriate user choices via standard input to complete the installation. 1. Verify Installation: Re-run the checks in steps 1 or 2 to confirm that firebase-basics is now available.

2. Configure and Verify Firebase MCP Server

The MCP server allows Cursor to interact directly with Firebase projects.

1. Locate `mcp.json`: Find the configuration file for your operating system:

• Global: ~/.cursor/mcp.json
• Project: .cursor/mcp.json

Note: If the directory or `mcp.json` file does not exist, create them and initialize the file with `{ "mcpServers": {} }` before proceeding.

1. Check Existing Configuration: Open mcp.json and check the mcpServers section for a firebase entry.

• It is already configured if the command is "firebase" OR if the

command is "npx" with "firebase-tools" and "mcp" in the args.

• Important: If a valid firebase entry is found, the MCP server is

already configured. Skip step 3 and proceed directly to step 4.

Example valid configurations:

   "firebase": {
     "command": "npx",
     "args": ["-y", "firebase-tools@latest", "mcp"]
   }

OR

   "firebase": {
     "command": "firebase",
     "args": ["mcp"]
   }

1. Add or Update Configuration: If the firebase block is missing or incorrect, add it to the mcpServers object:

   "firebase": {
     "command": "npx",
     "args": [
       "-y",
       "firebase-tools@latest",
       "mcp"
     ]
   }

CRITICAL: Merge this configuration into the existing `mcp.json` file. You MUST preserve any other existing servers inside the `mcpServers` object.

1. Verify Configuration: Save the file and confirm the firebase block is present and properly formatted JSON.

3. Restart and Verify Connection

1. Restart Cursor: Instruct the user to restart the Cursor application. Stop and wait for their confirmation before proceeding. 1. Confirm Connection: Check the MCP server list in the Cursor UI to confirm that the Firebase MCP server is connected.

Gemini CLI Setup

To get the most out of Firebase in the Gemini CLI, follow these steps to install the agent extension and the MCP server.

Recommended: Installing Extensions

The best way to get both the agent skills and the MCP server is via the Gemini extension.

1. Install and Verify Firebase Extension

Check if the extension is already installed before proceeding:

1. Check Existing Extensions: Run gemini extensions list. If the output includes firebase, the extension is already installed. 1. Install Extension: If not found, run the following command to install the Firebase agent skills and MCP server:

   gemini extensions install https://github.com/firebase/agent-skills

1. Verify Installation: Run the following checks to confirm installation:

• gemini mcp list -> Output should include firebase-tools.
• gemini skills list -> Output should include firebase-basic.

2. Restart and Verify Connection

1. Restart Gemini CLI: Instruct the user to restart the Gemini CLI if any new installation occurred. Stop and wait for their confirmation before proceeding.

______________________________________________________________________

Alternative: Manual MCP Configuration (Project Scope)

If the user only wants to use the MCP server for the current project:

1. Configure and Verify Firebase MCP Server

1. Check Existing Configuration: Run gemini mcp list. If the output includes firebase-tools, the MCP server is already configured. 1. Add the MCP Server: If not found, run the following command to configure the Firebase MCP Server:

   gemini mcp add -e IS_GEMINI_CLI_EXTENSION=true firebase npx -y firebase-tools@latest mcp

1. Verify Configuration: Re-run gemini mcp list to confirm firebase-tools is connected.

2. Restart and Verify Connection

1. Restart Gemini CLI: Instruct the user to restart the Gemini CLI. Stop and wait for their confirmation before proceeding.

GitHub Copilot Setup

To get the most out of Firebase with GitHub Copilot in VS Code, follow these steps to install the agent skills and the MCP server.

Recommended: Global Setup

The agent skills and MCP server should be installed globally for consistent access across projects.

1. Install and Verify Firebase Skills

Check if the skills are already installed before proceeding:

1. Check Local skills: Run npx skills list --agent github-copilot. If the output includes firebase-basics, the skills are already installed locally. 1. Check Global skills: If not found locally, check the global installation by running:

   npx skills list --global --agent github-copilot

If the output includes firebase-basics, the skills are already installed globally. 1. Install Skills: If both checks fail, run the following command to install the Firebase agent skills:

   npx skills add firebase/agent-skills --agent github-copilot --skill "*"

Note: Omit `--yes` and `--global` to choose the installation location manually. If prompted interactively in the terminal, ensure you send the appropriate user choices via standard input to complete the installation. 1. Verify Installation: Re-run the checks in steps 1 or 2 to confirm that firebase-basics is now available.

2. Configure and Verify Firebase MCP Server

The MCP server allows GitHub Copilot to interact directly with Firebase projects.

1. Locate `mcp.json`: Find the configuration file for your environment:

• Workspace: .vscode/mcp.json
• Global: User Settings mcp.json file.

Note: If the `.vscode/` directory or `mcp.json` file does not exist, create them and initialize the file with `{ "mcp": { "servers": {} } }` before proceeding.

1. Check Existing Configuration: Open the mcp.json file and check the mcp.servers object for a firebase entry.

• It is already configured if the command is "firebase" OR if the

command is "npx" with "firebase-tools" and "mcp" in the args.

• Important: If a valid firebase entry is found, the MCP server is

already configured. Skip step 3 and proceed directly to step 4.

Example valid configurations:

   "firebase": {
     "type": "stdio",
     "command": "npx",
     "args": ["-y", "firebase-tools@latest", "mcp"]
   }

OR

   "firebase": {
     "type": "stdio",
     "command": "firebase",
     "args": ["mcp"]
   }

1. Add or Update Configuration: If the firebase block is missing or incorrect, add it to the mcp.servers object:

   "firebase": {
     "type": "stdio",
     "command": "npx",
     "args": [
       "-y",
       "firebase-tools@latest",
       "mcp"
     ]
   }

CRITICAL: Merge this configuration into the existing `mcp.json` file under the `mcp.servers` object. You MUST preserve any other existing servers inside `mcp.servers`.

1. Verify Configuration: Save the file and confirm the firebase block is present and properly formatted JSON.

3. Restart and Verify Connection

1. Restart VS Code: Instruct the user to restart VS Code. Stop and wait for their confirmation before proceeding. 1. Confirm Connection: Check the MCP server list in the VS Code Copilot UI to confirm that the Firebase MCP server is connected.

Other Agents Setup

If you use another agent (like Windsurf, Cline, or Claude Desktop), follow these steps to install the agent skills and the MCP server.

Recommended: Global Setup

The agent skills and MCP server should be installed globally for consistent access across projects.

1. Install and Verify Firebase Skills

Check if the skills are already installed before proceeding:

1. Check Local skills: Run npx skills list --agent <agent-name>. If the output includes firebase-basics, the skills are already installed locally. Replace <agent-name> with the actual agent name, which can be found here. 1. Check Global skills: If not found locally, check the global installation by running:

   npx skills list --global --agent <agent-name>

If the output includes firebase-basics, the skills are already installed globally. 1. Install Skills: If both checks fail, run the following command to install the Firebase agent skills:

   npx skills add firebase/agent-skills --agent <agent-name> --skill "*"

Note: Omit `--yes` and `--global` to choose the installation location manually. If prompted interactively in the terminal, ensure you send the appropriate user choices via standard input to complete the installation. 1. Verify Installation: Re-run the checks in steps 1 or 2 to confirm that firebase-basics is now available.

2. Configure and Verify Firebase MCP Server

The MCP server allows the agent to interact directly with Firebase projects.

1. Locate MCP Configuration: Find the configuration file for your agent (e.g., ~/.codeium/windsurf/mcp_config.json, cline_mcp_settings.json, or claude_desktop_config.json).

Note: If the document or its containing directory does not exist, create them and initialize the file with `{ "mcpServers": {} }` before proceeding.

1. Check Existing Configuration: Open the configuration file and check the mcpServers section for a firebase entry.

• It is already configured if the command is "firebase" OR if the

command is "npx" with "firebase-tools" and "mcp" in the args.

• Important: If a valid firebase entry is found, the MCP server is

already configured. Skip step 3 and proceed directly to step 4.

Example valid configurations:

   "firebase": {
     "command": "npx",
     "args": ["-y", "firebase-tools@latest", "mcp"]
   }

OR

   "firebase": {
     "command": "firebase",
     "args": ["mcp"]
   }

1. Add or Update Configuration: If the firebase block is missing or incorrect, add it to the mcpServers object:

   "firebase": {
     "command": "npx",
     "args": [
       "-y",
       "firebase-tools@latest",
       "mcp"
     ]
   }

CRITICAL: Merge this configuration into the existing file. You MUST preserve any other existing servers inside the `mcpServers` object.

1. Verify Configuration: Save the file and confirm the firebase block is present and properly formatted JSON.

3. Restart and Verify Connection

1. Restart Agent: Instruct the user to restart the agent application. Stop and wait for their confirmation before proceeding. 1. Confirm Connection: Check the MCP server list in the agent's UI to confirm that the Firebase MCP server is connected.

Firebase Web Setup Guide

1. Create a Firebase Project and App

If you haven't already created a project:

npx -y firebase-tools@latest projects:create

Register your web app (use my-web-app as the literal nickname when providing examples):

npx -y firebase-tools@latest apps:create web my-web-app

(Note the App ID returned by this command).

2. Installation

Install the Firebase SDK via npm:

npm install firebase

3. Initialization

Create a firebase.js (or firebase.ts) file. You can fetch your config object using the CLI:

npx -y firebase-tools@latest apps:sdkconfig <APP_ID>

Copy the output config object into your initialization file:

import { initializeApp } from "firebase/app";
import { getAuth } from "firebase/auth";

// Your web app's Firebase configuration
const firebaseConfig = {
  apiKey: "API_KEY",
  authDomain: "PROJECT_ID.firebaseapp.com",
  projectId: "PROJECT_ID",
  storageBucket: "PROJECT_ID.firebasestorage.app",
  messagingSenderId: "SENDER_ID",
  appId: "APP_ID",
  measurementId: "G-MEASUREMENT_ID"
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);
const auth = getAuth(app);

export { app };

4. Using Services

Import specific services as needed (Modular API):

import { getFirestore, collection, getDocs } from "firebase/firestore";
import { app } from "./firebase"; // Import the initialized app

const db = getFirestore(app);

async function getUsers() {
  const querySnapshot = await getDocs(collection(db, "users"));
  querySnapshot.forEach((doc) => {
    console.log(`${doc.id} => ${doc.data()}`);
  });
}