Firebase MCP Server

Instructions

Implementation Reference

• src/lib/firebase/firestoreClient.ts:61-117 (handler)

  Core handler function for firestore_list_documents tool: queries Firestore collection with optional filters, pagination via pageToken, converts timestamps, generates console URLs, and returns paginated document list with total count.
  export async function listDocuments(collection: string, filters: Array<{ field: string, operator: FirebaseFirestore.WhereFilterOp, value: any }> = [], limit: number = 20, pageToken?: string) { const projectId = getProjectId(); try { if (!db) { return { content: [{ type: 'text', text: 'Firebase is not initialized. SERVICE_ACCOUNT_KEY_PATH environment variable is required.' }], isError: true }; } const collectionRef = db.collection(collection); let filteredQuery: Query = collectionRef; for (const filter of filters) { let filterValue = filter.value; if (typeof filterValue === 'string' && !isNaN(Date.parse(filterValue))) { filterValue = Timestamp.fromDate(new Date(filterValue)); } filteredQuery = filteredQuery.where(filter.field, filter.operator, filterValue); } // Apply pageToken if provided if (pageToken) { const startAfterDoc = await collectionRef.doc(pageToken).get(); filteredQuery = filteredQuery.startAfter(startAfterDoc); } // Get total count of documents matching the filter const countSnapshot = await filteredQuery.get(); const totalCount = countSnapshot.size; // Get the first 'limit' documents const limitedQuery = filteredQuery.limit(limit); const snapshot = await limitedQuery.get(); if (snapshot.empty) { return { content: [{ type: 'text', text: 'No matching documents found' }], isError: true }; } const documents = snapshot.docs.map((doc: any) => { const data = doc.data(); convertTimestampsToISO(data); const consoleUrl = `https://console.firebase.google.com/project/${projectId}/firestore/data/${collection}/${doc.id}`; return { id: doc.id, url: consoleUrl, document: data }; }); return { content: [{ type: 'text', text: JSON.stringify({ totalCount, documents, pageToken: documents.length > 0 ? documents[documents.length - 1].id : null, hasMore: totalCount > limit }) }] }; } catch (error) { return { content: [{ type: 'text', text: `Error listing documents: ${(error as Error).message}` }], isError: true }; } }
• src/index.ts:79-121 (schema)

  Input schema definition for the firestore_list_documents tool, including parameters for collection, filters, limit, and pageToken.
  name: 'firestore_list_documents', description: 'List documents from a Firestore collection with optional filtering', inputSchema: { type: 'object', properties: { collection: { type: 'string', description: 'Collection name' }, filters: { type: 'array', description: 'Array of filter conditions', items: { type: 'object', properties: { field: { type: 'string', description: 'Field name to filter' }, operator: { type: 'string', description: 'Comparison operator' }, value: { type: 'any', description: 'Value to compare against (use ISO format for dates)' } }, required: ['field', 'operator', 'value'] } }, limit: { type: 'number', description: 'Number of documents to return', default: 20 }, pageToken: { type: 'string', description: 'Token for pagination to get the next page of results' } }, required: ['collection'] }
• src/index.ts:231-237 (registration)

  Tool dispatch/registration in the CallToolRequestSchema handler: maps tool call to the listDocuments implementation.
  case 'firestore_list_documents': return listDocuments( args.collection as string, args.filters as Array<{ field: string, operator: FirebaseFirestore.WhereFilterOp, value: any }>, args.limit as number, args.pageToken as string | undefined );
• src/lib/firebase/firestoreClient.ts:51-58 (helper)

  Helper function used in listDocuments to convert Firestore Timestamp fields to ISO strings for JSON output.
  function convertTimestampsToISO(data: any) { for (const key in data) { if (data[key] instanceof Timestamp) { data[key] = data[key].toDate().toISOString(); } } return data; }