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

Introduction ## hummer98 / firex ## Firebase Firestore CLI tool for command-line operations - Read, write, query, and manage Firestore data from your terminal ## Table of Contents ## Features ## What is firex? ## Key Features ## 1. Basic CRUD Operations ## 2. Complex Queries ## 3. Real-time Monitoring ## 4. Export & Import ## 5. Multiple Project Support ## 6. Output Format Options ## 7. Timestamp Display Formats (New in v0.6.0) ## 8. Environment Diagnostics (New in v0.5.0) ## AI Coding Agent Integration (MCP Server) ## Why Do We Need an MCP Server? ## What is MCP? ## For Claude Code ## For Claude Desktop ## Available MCP Tools ## Comparison with Other Tools ## Quick Start ## 1. Authentication Setup ## 2. Run ## Use Cases ## Check and Debug Production Data ## Data Backup and Migration ## Real-time Debugging During Development ## Data Operations via AI Coding Agent ## Installation ## Conclusion ## hummer98 / firex ## Firebase Firestore CLI tool for command-line operations - Read, write, query, and manage Firestore data from your terminal ## Table of Contents ## Features Have you ever felt frustrated with Firestore and thought: To solve these problems, I created a CLI tool called 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. 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. Additionally, it works as an MCP (Model Context Protocol) server, allowing AI coding agents like Claude Code and Gemini CLI to directly operate Firestore. You can perform queries with multiple conditions - something firebase-tools can't do: Use the --watch flag to monitor document or collection changes in real-time: This is useful for debugging during development or monitoring production environments. Manage multiple environments with .firex.yaml: Choose the output format based on your needs: Format timestamps according to your preference: The doctor command helps diagnose your environment setup: The standout feature of firex is that it works as an MCP server. Have you ever seen an AI coding agent try to access Firestore with commands like this? 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. 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). Add to ~/Library/Application Support/Claude/claude_desktop_config.json: After setup, just give natural language instructions to the AI: The AI will call the appropriate firex tools to operate Firestore. In 2025, Google released the official Firebase MCP Server. Here's how firex compares: With Claude Code or Gemini CLI: 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! 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. Templates let you quickly answer FAQs or store snippets for re-use. Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment's permalink. Hide child comments as well For further actions, you may consider blocking this person and/or reporting abuse COMMAND_BLOCK: # Run instantly without installation npx @hummer98/firex list users --where "status==active" --limit 10 Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: # Run instantly without installation npx @hummer98/firex list users --where "status==active" --limit 10 COMMAND_BLOCK: # Run instantly without installation npx @hummer98/firex list users --where "status==active" --limit 10 COMMAND_BLOCK: # 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 COMMAND_BLOCK: # 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 COMMAND_BLOCK: # 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 COMMAND_BLOCK: # 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 COMMAND_BLOCK: # Multiple WHERE conditions + sort + limit firex list products \ --where "category==electronics" \ --where "price>1000" \ --order-by price --order-dir desc \ --limit 20 COMMAND_BLOCK: # Multiple WHERE conditions + sort + limit firex list products \ --where "category==electronics" \ --where "price>1000" \ --order-by price --order-dir desc \ --limit 20 COMMAND_BLOCK: # Watch document changes firex get users/user123 --watch # Watch collection changes firex list orders --watch Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: # Watch document changes firex get users/user123 --watch # Watch collection changes firex list orders --watch COMMAND_BLOCK: # Watch document changes firex get users/user123 --watch # Watch collection changes firex list orders --watch COMMAND_BLOCK: # 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 COMMAND_BLOCK: # 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 COMMAND_BLOCK: # 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 COMMAND_BLOCK: # .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 COMMAND_BLOCK: # .firex.yaml projectId: dev-project credentialPath: ./dev-service-account.json profiles: staging: projectId: staging-project production: projectId: prod-project credentialPath: ./prod-service-account.json COMMAND_BLOCK: # .firex.yaml projectId: dev-project credentialPath: ./dev-service-account.json profiles: staging: projectId: staging-project production: projectId: prod-project credentialPath: ./prod-service-account.json COMMAND_BLOCK: # Check production data firex list users --profile production Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: # Check production data firex list users --profile production COMMAND_BLOCK: # Check production data firex list users --profile production COMMAND_BLOCK: 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 COMMAND_BLOCK: 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) COMMAND_BLOCK: 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) COMMAND_BLOCK: 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 COMMAND_BLOCK: 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 COMMAND_BLOCK: 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 COMMAND_BLOCK: # 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 COMMAND_BLOCK: # Check your environment firex doctor # JSON output for CI/CD firex doctor --json # Verbose output for debugging firex doctor --verbose COMMAND_BLOCK: # Check your environment firex doctor # JSON output for CI/CD firex doctor --json # Verbose output for debugging firex doctor --verbose COMMAND_BLOCK: # 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 COMMAND_BLOCK: # Non-existent command that AI tends to generate gcloud firestore documents get projects/PROJECT_ID/databases/(default)/documents/users/user123 COMMAND_BLOCK: # Non-existent command that AI tends to generate gcloud firestore documents get projects/PROJECT_ID/databases/(default)/documents/users/user123 CODE_BLOCK: 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 CODE_BLOCK: claude mcp add firex \ -e FIRESTORE_PROJECT_ID=your-project-id \ -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json \ -- npx @hummer98/firex mcp CODE_BLOCK: claude mcp add firex \ -e FIRESTORE_PROJECT_ID=your-project-id \ -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json \ -- npx @hummer98/firex mcp CODE_BLOCK: { "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 CODE_BLOCK: { "mcpServers": { "firex": { "command": "npx", "args": ["@hummer98/firex", "mcp"], "env": { "FIRESTORE_PROJECT_ID": "your-project-id", "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json" } } } } CODE_BLOCK: { "mcpServers": { "firex": { "command": "npx", "args": ["@hummer98/firex", "mcp"], "env": { "FIRESTORE_PROJECT_ID": "your-project-id", "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json" } } } } CODE_BLOCK: "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 CODE_BLOCK: "Get 10 users with status 'active' from the users collection" "Update user123's lastLogin to today's date" "Export the orders collection" CODE_BLOCK: "Get 10 users with status 'active' from the users collection" "Update user123's lastLogin to today's date" "Export the orders collection" COMMAND_BLOCK: # 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 COMMAND_BLOCK: # 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 COMMAND_BLOCK: # 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 COMMAND_BLOCK: # 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 COMMAND_BLOCK: # 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 COMMAND_BLOCK: # 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 COMMAND_BLOCK: # 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 COMMAND_BLOCK: # 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 COMMAND_BLOCK: # 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 COMMAND_BLOCK: # 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 COMMAND_BLOCK: # Export from production firex export users --profile production --output users-backup.json # Import to staging firex import users-backup.json --profile staging COMMAND_BLOCK: # Export from production firex export users --profile production --output users-backup.json # Import to staging firex import users-backup.json --profile staging COMMAND_BLOCK: # Monitor data changes while operating the frontend firex list orders --watch Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: # Monitor data changes while operating the frontend firex list orders --watch COMMAND_BLOCK: # Monitor data changes while operating the frontend firex list orders --watch CODE_BLOCK: "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 CODE_BLOCK: "Get orders from the past week and calculate the total amount" "Update all orders with status='pending' to 'processing'" CODE_BLOCK: "Get orders from the past week and calculate the total amount" "Update all orders with status='pending' to 'processing'" COMMAND_BLOCK: # Global installation npm install -g @hummer98/firex # Or run with npx (no installation needed) npx @hummer98/firex [command] Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: # Global installation npm install -g @hummer98/firex # Or run with npx (no installation needed) npx @hummer98/firex [command] COMMAND_BLOCK: # Global installation npm install -g @hummer98/firex # Or run with npx (no installation needed) npx @hummer98/firex [command] - "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" - Installation - Quick Start - Command Reference - Configuration File - Environment Variables - Troubleshooting - Security Considerations - TOON Output Format - MCP Server Integration - Development - Requirements - Contributing - 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… - Node.js version (requires 18.0.0+) - Firebase CLI installation - Authentication (ADC or Service Account) - Firestore API access - Config file validation - Emulator connection - 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 - Installation - Quick Start - Command Reference - Configuration File - Environment Variables - Troubleshooting - Security Considerations - TOON Output Format - MCP Server Integration - Development - Requirements - Contributing - 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… - npm: @hummer98/firex - MCP (Model Context Protocol) - Claude Code - Firebase MCP Server