DEV Community

Cover image for I Built 'firex' - A CLI Tool for Firestore Operations with AI Agent Integration
Yuji Yamamoto
Yuji Yamamoto

Posted on

I Built 'firex' - A CLI Tool for Firestore Operations with AI Agent Integration

#firebase #firestore #cli #mcp

Introduction

Have you ever felt frustrated with Firestore and thought:

  • "I just want to quickly check some data, but opening the console every time is tedious..."
  • "I want to export production data to my local environment"
  • "I need to query with multiple WHERE conditions, but the console has limitations"
  • "I want Claude Code or Gemini CLI to directly operate Firestore"

To solve these problems, I created a CLI tool called firex.

GitHub logo hummer98 / firex

Firebase Firestore CLI tool for command-line operations - Read, write, query, and manage Firestore data from your terminal

English | 日本語

firex banner

firex

Firebase Firestore CLI tool for command-line operations.

firex is a powerful command-line interface tool for managing Firebase Firestore databases. It allows developers to perform CRUD operations, execute queries, and manage data efficiently without relying on the Firebase Console GUI. It also works as an MCP (Model Context Protocol) server, enabling AI assistants like Claude to interact with Firestore directly.

Table of Contents

Features

  • Document Operations: Read, create, update, and delete Firestore documents
  • Collection Queries: List documents with filtering, sorting, and pagination
  • Batch Operations: Import and export collections to/from JSON files
  • Real-time Monitoring: Watch documents and collections for changes with --watch flag
  • Multiple Output Formats: JSON, YAML, table, and TOON format support
  • Timestamp Formatting: Flexible timestamp display…
View on GitHub

What is firex?

It's a CLI tool that lets you perform CRUD operations on Firestore directly from your terminal.

Surprisingly, neither the firebase CLI nor the gcloud CLI provides commands to get or manipulate Firestore documents. firex fills this gap.

# Run instantly without installation
npx @hummer98/firex list users --where "status==active" --limit 10
Enter fullscreen mode Exit fullscreen mode

Additionally, it works as an MCP (Model Context Protocol) server, allowing AI coding agents like Claude Code and Gemini CLI to directly operate Firestore.

Key Features

1. Basic CRUD Operations 

# Get a document
firex get users/user123

# List a collection
firex list users

# Create or update a document
firex set users/user123 '{"name": "John", "status": "active"}'

# Partial update
firex update users/user123 '{"lastLogin": "2024-12-20"}'

# Delete
firex delete users/user123
Enter fullscreen mode Exit fullscreen mode

2. Complex Queries

You can perform queries with multiple conditions - something firebase-tools can't do:

# Multiple WHERE conditions + sort + limit
firex list products \
  --where "category==electronics" \
  --where "price>1000" \
  --order-by price --order-dir desc \
  --limit 20
Enter fullscreen mode Exit fullscreen mode

3. Real-time Monitoring

Use the --watch flag to monitor document or collection changes in real-time:

# Watch document changes
firex get users/user123 --watch

# Watch collection changes
firex list orders --watch
Enter fullscreen mode Exit fullscreen mode

This is useful for debugging during development or monitoring production environments.

4. Export & Import 

# Export a collection to JSON
firex export users --output backup.json

# Export including subcollections
firex export users --output full-backup.json --include-subcollections

# Import
firex import backup.json
Enter fullscreen mode Exit fullscreen mode

5. Multiple Project Support

Manage multiple environments with .firex.yaml:

# .firex.yaml
projectId: dev-project
credentialPath: ./dev-service-account.json

profiles:
  staging:
    projectId: staging-project
  production:
    projectId: prod-project
    credentialPath: ./prod-service-account.json
Enter fullscreen mode Exit fullscreen mode 
# Check production data
firex list users --profile production
Enter fullscreen mode Exit fullscreen mode

6. Output Format Options

Choose the output format based on your needs:

firex list users --format json   # JSON (default)
firex list users --format yaml   # YAML
firex list users --format table  # Human-readable table
firex list users --format toon   # Token-optimized (for AI agents)
Enter fullscreen mode Exit fullscreen mode

7. Timestamp Display Formats (New in v0.6.0)

Format timestamps according to your preference:

firex list logs --timestamp-format iso       # 2024-12-22T10:30:00.000Z (default)
firex list logs --timestamp-format locale    # 12/22/2024, 10:30:00 AM
firex list logs --timestamp-format relative  # 2 hours ago
firex list logs --timestamp-format unix      # 1703241000
firex list logs --timestamp-format unix-ms   # 1703241000000
Enter fullscreen mode Exit fullscreen mode

8. Environment Diagnostics (New in v0.5.0)

The doctor command helps diagnose your environment setup:

# Check your environment
firex doctor

# JSON output for CI/CD
firex doctor --json

# Verbose output for debugging
firex doctor --verbose
Enter fullscreen mode Exit fullscreen mode

It checks:

  • Node.js version (requires 18.0.0+)
  • Firebase CLI installation
  • Authentication (ADC or Service Account)
  • Firestore API access
  • Config file validation
  • Emulator connection

AI Coding Agent Integration (MCP Server)

The standout feature of firex is that it works as an MCP server.

Why Do We Need an MCP Server?

Have you ever seen an AI coding agent try to access Firestore with commands like this?

# Non-existent command that AI tends to generate
gcloud firestore documents get projects/PROJECT_ID/databases/(default)/documents/users/user123
Enter fullscreen mode Exit fullscreen mode

As mentioned earlier, CLI commands for Firestore operations don't exist, so AI generates fictional commands.

By registering firex as an MCP server, AI can use the correct tools to operate Firestore.

What is MCP?

MCP (Model Context Protocol) is a protocol for AI to integrate with external tools. It was created by Anthropic and is now adopted by many AI coding agents including Claude Code, Gemini CLI, and VS Code (GitHub Copilot).

Setup

For Claude Code 

claude mcp add firex \
  -e FIRESTORE_PROJECT_ID=your-project-id \
  -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json \
  -- npx @hummer98/firex mcp
Enter fullscreen mode Exit fullscreen mode

For Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "firex": {
      "command": "npx",
      "args": ["@hummer98/firex", "mcp"],
      "env": {
        "FIRESTORE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Usage

After setup, just give natural language instructions to the AI:

"Get 10 users with status 'active' from the users collection"

"Update user123's lastLogin to today's date"

"Export the orders collection"
Enter fullscreen mode Exit fullscreen mode

The AI will call the appropriate firex tools to operate Firestore.

Available MCP Tools

Tool Name Description
firestore_get Get a document
firestore_list Query a collection
firestore_set Create or update a document
firestore_update Partial update
firestore_delete Delete a document
firestore_collections List collections
firestore_export Export data
firestore_import Import data

Comparison with Other Tools

In 2025, Google released the official Firebase MCP Server. Here's how firex compares:

Feature firex Firebase MCP Server
Get document Yes Yes
Query (filter) Yes Yes
Create/Update document Yes Unknown
Delete document Yes Yes
Export/Import Yes No
Works as CLI Yes No (MCP only)
Real-time monitoring Yes (--watch) No
Timestamp formatting Yes No
Environment diagnostics Yes (doctor) No
Manage all Firebase No Yes (Auth, Storage, etc.)

When to use which:

  • firex: Specialized for Firestore data operations. Use when you also want a CLI, need export/import, or prefer detailed timestamp control
  • Firebase MCP: Use when you want to manage all of Firebase (Auth, Storage, Hosting, etc.) with AI

Quick Start

1. Authentication Setup 

# Option A: Service account key
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

# Option B: gcloud ADC
gcloud auth application-default login

# Option C: Emulator (for development)
export FIRESTORE_EMULATOR_HOST=localhost:8080
Enter fullscreen mode Exit fullscreen mode

2. Run 

# Specify project ID
npx @hummer98/firex list users --project-id your-project-id

# Or set via environment variable
export FIRESTORE_PROJECT_ID=your-project-id
npx @hummer98/firex list users
Enter fullscreen mode Exit fullscreen mode

Use Cases

Check and Debug Production Data 

# Check a specific user's data
firex get users/problematic-user-id

# Check recently created documents
firex list logs --order-by createdAt --order-dir desc --limit 5
Enter fullscreen mode Exit fullscreen mode

Data Backup and Migration 

# Export from production
firex export users --profile production --output users-backup.json

# Import to staging
firex import users-backup.json --profile staging
Enter fullscreen mode Exit fullscreen mode

Real-time Debugging During Development 

# Monitor data changes while operating the frontend
firex list orders --watch
Enter fullscreen mode Exit fullscreen mode

Data Operations via AI Coding Agent

With Claude Code or Gemini CLI:

"Get orders from the past week and calculate the total amount"
"Update all orders with status='pending' to 'processing'"
Enter fullscreen mode Exit fullscreen mode

Installation 

# Global installation
npm install -g @hummer98/firex

# Or run with npx (no installation needed)
npx @hummer98/firex [command]
Enter fullscreen mode Exit fullscreen mode

Conclusion

firex was born from my personal desire to "interact with Firestore from the terminal."

The MCP server feature is especially useful when developing Firebase projects with Claude Code or Gemini CLI. Just say "show me this data" or "update that field," and the AI handles it for you.

Feedback and feature requests are welcome on GitHub Issues and Discussions!

GitHub logo hummer98 / firex

Firebase Firestore CLI tool for command-line operations - Read, write, query, and manage Firestore data from your terminal

English | 日本語

firex banner

firex

Firebase Firestore CLI tool for command-line operations.

firex is a powerful command-line interface tool for managing Firebase Firestore databases. It allows developers to perform CRUD operations, execute queries, and manage data efficiently without relying on the Firebase Console GUI. It also works as an MCP (Model Context Protocol) server, enabling AI assistants like Claude to interact with Firestore directly.

Table of Contents

Features

  • Document Operations: Read, create, update, and delete Firestore documents
  • Collection Queries: List documents with filtering, sorting, and pagination
  • Batch Operations: Import and export collections to/from JSON files
  • Real-time Monitoring: Watch documents and collections for changes with --watch flag
  • Multiple Output Formats: JSON, YAML, table, and TOON format support
  • Timestamp Formatting: Flexible timestamp display…
View on GitHub

Related Links

Top comments (0)