Skip to content
Back to search

firebase-mcp

πŸ”₯ Model Context Protocol (MCP) server for Firebase.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gannonh--firebase-mcp/badge.svg)](/listings/gannonh--firebase-mcp)

HTML

<a href="/listings/gannonh--firebase-mcp"><img src="/api/listings/gannonh--firebase-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Firebase project with service account credentials - Node.js environment

1. Install MCP Server

Add the server configuration to your MCP settings file:

- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json` - Augment: `~/Library/Application Support/Code/User/settings.json` - Cursor: `[project root]/.cursor/mcp.json`

MCP Servers can be installed manually or at runtime via npx (recommended). How you install determines your configuration:

Configure for npx (recommended)

   {
     "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"
       }
     }
   }

Configure for local installation

   {
     "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. Test the Installation

Ask your AI client: "Please test all Firebase MCP tools."

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 340 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Firebase MCP
  2. ![Project Logo](./assets/logo.png)
  3. <a href="https://glama.ai/mcp/servers/x4i8z2xmrq">
  4. <img width="380" height="200" src="https://glama.ai/mcp/servers/x4i8z2xmrq/badge" alt="Firebase MCP server" />
  5. </a>
  6. [![Firebase Tests CI](https://github.com/gannonh/firebase-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/gannonh/firebase-mcp/actions/workflows/tests.yml)
  7. ## Overview
  8. **Firebase MCP** enables AI assistants to work directly with Firebase services, including:
  9. - **Firestore**: Document database operations
  10. - **Storage**: File management with robust upload capabilities
  11. - **Authentication**: User management and verification
  12. The server works with MCP client applicatios such as [Claude Desktop](https://claude.ai/download), [Augment Code](https://docs.augmentcode.com/setup-augment/mcp), [VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers), and [Cursor](https://www.cursor.com/).
  13. > ⚠️ **Known Issue**: The `firestore_list_collections` tool may return a Zod validation error in the client logs. This is an erroneous validation error in the MCP SDK, as our investigation confirmed no boolean values are present in the response. Despite the error message, the query still works correctly and returns the proper collection data. This is a log-level error that doesn't affect functionality.
  14. ## ⚑ Quick Start
  15. ### Prerequisites
  16. - Firebase project with service account credentials
  17. - Node.js environment
  18. ### 1. Install MCP Server
  19. Add the server configuration to your MCP settings file:
  20. - Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`
  21. - Augment: `~/Library/Application Support/Code/User/settings.json`
  22. - Cursor: `[project root]/.cursor/mcp.json`
  23. MCP Servers can be installed manually or at runtime via npx (recommended). How you install determines your configuration:
  24. #### Configure for npx (recommended)
  25. ```json
  26. {
  27. "firebase-mcp": {
  28. "command": "npx",
  29. "args": [
  30. "-y",
  31. "@gannonh/firebase-mcp"
  32. ],
  33. "env": {
  34. "SERVICE_ACCOUNT_KEY_PATH": "/absolute/path/to/serviceAccountKey.json",
  35. "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"
  36. }
  37. }
  38. }
  39. ```
  40. #### Configure for local installation
  41. ```json
  42. {
  43. "firebase-mcp": {
  44. "command": "node",
  45. "args": [
  46. "/absolute/path/to/firebase-mcp/dist/index.js"
  47. ],
  48. "env": {
  49. "SERVICE_ACCOUNT_KEY_PATH": "/absolute/path/to/serviceAccountKey.json",
  50. "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"
  51. }
  52. }
  53. }
  54. ```
  55. ### 2. Test the Installation
  56. Ask your AI client: "Please test all Firebase MCP tools."
  57. ## πŸ› οΈ Setup & Configuration
  58. ### 1. Firebase Configuration
  59. 1. Go to [Firebase Console](https://console.firebase.google.com) β†’ Project Settings β†’ Service Accounts
  60. 2. Click "Generate new private key"
  61. 3. Save the JSON file securely
  62. ### 2. Environment Variables
  63. #### Required
  64. - `SERVICE_ACCOUNT_KEY_PATH`: Path to your Firebase service account key JSON (required)
  65. #### Optional
  66. - `FIREBASE_STORAGE_BUCKET`: Bucket name for Firebase Storage (defaults to `[projectId].appspot.com`)
  67. - `MCP_TRANSPORT`: Transport type to use (`stdio` or `http`) (defaults to `stdio`)
  68. - `MCP_HTTP_PORT`: Port for HTTP transport (defaults to `3000`)
  69. - `MCP_HTTP_HOST`: Host for HTTP transport (defaults to `localhost`)
  70. - `MCP_HTTP_PATH`: Path for HTTP transport (defaults to `/mcp`)
  71. - `DEBUG_LOG_FILE`: Enable file logging:
  72. - Set to `true` to log to `~/.firebase-mcp/debug.log`
  73. - Set to a file path to log to a custom location
  74. ### 3. Client Integration
  75. #### Claude Desktop
  76. Edit: `~/Library/Application Support/Claude/claude_desktop_config.json`
  77. #### VS Code / Augment
  78. Edit: `~/Library/Application Support/Code/User/settings.json`
  79. #### Cursor
  80. Edit: `[project root]/.cursor/mcp.json`
  81. ## πŸ“š API Reference
  82. ### Firestore Tools
  83. | Tool | Description | Required Parameters |
  84. | ---------------------------------- | ------------------------------ | -------------------------- |
  85. | `firestore_add_document` | Add a document to a collection | `collection`, `data` |
  86. | `firestore_list_documents` | List documents with filtering | `collection` |
  87. | `firestore_get_document` | Get a specific document | `collection`, `id` |
  88. | `firestore_update_document` | Update an existing document | `collection`, `id`, `data` |
  89. | `firestore_delete_document` | Delete a document | `collection`, `id` |
  90. | `firestore_list_collections` | List root collections | None |
  91. | `firestore_query_collection_group` | Query across subcollections | `collectionId` |
  92. ### Storage Tools
  93. | Tool | Description | Required Parameters |
  94. | ------------------------- | ------------------------- | -------------------------------- |
  95. | `storage_list_files` | List files in a directory | None (optional: `directoryPath`) |
  96. | `storage_get_file_info` | Get file metadata and URL | `filePath` |
  97. | `storage_upload` | Upload file from content | `filePath`, `content` |
  98. | `storage_upload_from_url` | Upload file from URL | `filePath`, `url` |
  99. ### Authentication Tools
  100. | Tool | Description | Required Parameters |
  101. | --------------- | ----------------------- | ------------------- |
  102. | `auth_get_user` | Get user by ID or email | `identifier` |
  103. ## πŸ’» Developer Guide
  104. ### Installation & Building
  105. ```bash
  106. git clone https://github.com/gannonh/firebase-mcp
  107. cd firebase-mcp
  108. npm install
  109. npm run build
  110. ```
  111. ### Running Tests
  112. First, install and start Firebase emulators:
  113. ```bash
  114. npm install -g firebase-tools
  115. firebase init emulators
  116. firebase emulators:start
  117. ```
  118. Then run tests:
  119. ```bash
  120. # Run tests with emulator
  121. npm run test:emulator
  122. # Run tests with coverage
  123. npm run test:coverage:emulator
  124. ```
  125. ### Project Structure
  126. ```bash
  127. src/
  128. β”œβ”€β”€ index.ts # Server entry point
  129. β”œβ”€β”€ utils/ # Utility functions
  130. └── lib/
  131. └── firebase/ # Firebase service clients
  132. β”œβ”€β”€ authClient.ts # Authentication operations
  133. β”œβ”€β”€ firebaseConfig.ts # Firebase configuration
  134. β”œβ”€β”€ firestoreClient.ts # Firestore operations
  135. └── storageClient.ts # Storage operations
  136. ```
  137. ## 🌐 HTTP Transport
  138. Firebase MCP now supports HTTP transport in addition to the default stdio transport. This allows you to run the server as a standalone HTTP service that can be accessed by multiple clients.
  139. ### Running with HTTP Transport
  140. To run the server with HTTP transport:
  141. ```bash
  142. # Using environment variables
  143. MCP_TRANSPORT=http MCP_HTTP_PORT=3000 node dist/index.js
  144. # Or with npx
  145. MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npx @gannonh/firebase-mcp
  146. ```
  147. ### Client Configuration for HTTP
  148. When using HTTP transport, configure your MCP client to connect to the HTTP endpoint:
  149. ```json
  150. {
  151. "firebase-mcp": {
  152. "url": "http://localhost:3000/mcp"
  153. }
  154. }
  155. ```
  156. ### Session Management
  157. The HTTP transport supports session management, allowing multiple clients to connect to the same server instance. Each client receives a unique session ID that is used to maintain state between requests.
  158. ## πŸ” Troubleshooting
  159. ### Common Issues
  160. #### Storage Bucket Not Found
  161. If you see "The specified bucket does not exist" error:
  162. 1. Verify your bucket name in Firebase Console β†’ Storage
  163. 2. Set the correct bucket name in `FIREBASE_STORAGE_BUCKET` environment variable
  164. #### Firebase Initialization Failed
  165. If you see "Firebase is not initialized" error:
  166. 1. Check that your service account key path is correct and absolute
  167. 2. Ensure the service account has proper permissions for Firebase services
  168. #### Composite Index Required
  169. If you receive "This query requires a composite index" error:
  170. 1. Look for the provided URL in the error message
  171. 2. Follow the link to create the required index in Firebase Console
  172. 3. Retry your query after the index is created (may take a few minutes)
  173. #### Zod Validation Error with `firestore_list_collections`
  174. If you see a Zod validation error with message "Expected object, received boolean" when using the `firestore_list_collections` tool:
  175. > ⚠️ **Known Issue**: The `firestore_list_collections` tool may return a Zod validation error in the client logs. This is an erroneous validation error in the MCP SDK, as our investigation confirmed no boolean values are present in the response. Despite the error message, the query still works correctly and returns the proper collection data. This is a log-level error that doesn't affect functionality.
  176. ### Debugging
  177. #### Enable File Logging
  178. To help diagnose issues, you can enable file logging:
  179. ```bash
  180. # Log to default location (~/.firebase-mcp/debug.log)
  181. DEBUG_LOG_FILE=true npx @gannonh/firebase-mcp
  182. # Log to a custom location
  183. DEBUG_LOG_FILE=/path/to/custom/debug.log npx @gannonh/firebase-mcp
  184. ```
  185. You can also enable logging in your MCP client configuration:
  186. ```json
  187. {
  188. "firebase-mcp": {
  189. "command": "npx",
  190. "args": ["-y", "@gannonh/firebase-mcp"],
  191. "env": {
  192. "SERVICE_ACCOUNT_KEY_PATH": "/path/to/serviceAccountKey.json",
  193. "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app",
  194. "DEBUG_LOG_FILE": "true"
  195. }
  196. }
  197. }
  198. ```
  199. #### Real-time Log Viewing
  200. To view logs in real-time:
  201. ```bash
  202. # Using tail to follow the log file
  203. tail -f ~/.firebase-mcp/debug.log
  204. # Using a split terminal to capture stderr
  205. npm start 2>&1 | tee logs.txt
  206. ```
  207. #### Using MCP Inspector
  208. The MCP Inspector provides interactive debugging:
  209. ```bash
  210. # Install MCP Inspector
  211. npm install -g @mcp/inspector
  212. # Connect to your MCP server
  213. mcp-inspector --connect stdio --command "node ./dist/index.js"
  214. ```
  215. ## πŸ“‹ Response Formatting
  216. ### Storage Upload Response Example
  217. ```json
  218. {
  219. "name": "reports/quarterly.pdf",
  220. "size": "1024000",
  221. "contentType": "application/pdf",
  222. "updated": "2025-04-11T15:37:10.290Z",
  223. "downloadUrl": "https://storage.googleapis.com/bucket/reports/quarterly.pdf?alt=media",
  224. "bucket": "your-project.appspot.com"
  225. }
  226. ```
  227. Displayed to the user as:
  228. ```markdown
  229. ## File Successfully Uploaded! πŸ“
  230. Your file has been uploaded to Firebase Storage:
  231. **File Details:**
  232. - **Name:** reports/quarterly.pdf
  233. - **Size:** 1024000 bytes
  234. - **Type:** application/pdf
  235. - **Last Updated:** April 11, 2025 at 15:37:10 UTC
  236. **[Click here to download your file](https://storage.googleapis.com/bucket/reports/quarterly.pdf?alt=media)**
  237. ```
  238. ## 🀝 Contributing
  239. 1. Fork the repository
  240. 2. Create a feature branch
  241. 3. Implement changes with tests (80%+ coverage required)
  242. 4. Submit a pull request
  243. ## πŸ“„ License
  244. MIT License - see [LICENSE](LICENSE) file for details
  245. ## πŸ”— Related Resources
  246. - [Model Context Protocol Documentation](https://github.com/modelcontextprotocol)
  247. - [Firebase Documentation](https://firebase.google.com/docs)
  248. - [Firebase Admin SDK](https://firebase.google.com/docs/admin/setup)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.