> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentruntime.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Firestore connector

> Query, update, and manage Google Cloud Firestore documents from AgentRuntime workflow steps.

The **firestore** MCP adapter connects to Google Cloud Firestore with a project ID, optional database ID, and Google service account credentials. It provides document reads, writes, collection queries, and security-rules tooling (`get_rules`, `validate_rules`). Use it for app backends, event logs, configuration stores, user profile sync, and rules validation in workflows — authenticated with a service account JSON key or Application Default Credentials (ADC).

## Prerequisites

* A Google Cloud project with Firestore enabled (Native mode)
* A Google service account with Firestore permissions:
  * **Cloud Datastore User** — read-only workflows (`firestore_get_documents`, `firestore_query_collection`, `firestore_list_collections`)
  * **Cloud Datastore Owner** or a scoped custom role — workflows that write or delete documents
* `ProjectID` and optional `Database` ID (default `(default)`)
* Google credentials via one of:
  * **Service account JSON key (`CredsJSON`)** — paste the full key JSON into the connection, or provide the key file path on the connector host
  * **Application Default Credentials (ADC)** — workload identity on GCE/GKE/Cloud Run, or `gcloud auth application-default login` on the connector host for local development
* **project\_contributor** access

## Connect in AgentRuntime

<Steps>
  <Step title="Create a Google service account">
    In [Google Cloud Console](https://console.cloud.google.com/), create a service account with Firestore access. Grant **Cloud Datastore User** for read workflows or **Cloud Datastore Owner** for read/write. Download the JSON key file, or configure workload identity on the connector host so ADC resolves automatically.
  </Step>

  <Step title="Create a connection">
    Go to **Connections** and click **New custom connection** to create a connection with:

    * `ProjectID` — your Google Cloud project ID
    * `Database` — Firestore database ID (omit for `(default)`)
    * `CredsJSON` — paste the full service account JSON key contents, or provide the key file path

    Omit `CredsJSON` only when the connector host provides Application Default Credentials (e.g. GCE workload identity or `gcloud auth application-default login` on the runtime host).
  </Step>

  <Step title="Add firestore MCP instance">
    Go to **MCP**, click **Add instance** for **firestore**, wire your connection on **Instance config**, set the profile **active**, and save.
  </Step>

  <Step title="Test with a collection listing">
    Add a workflow with **mcp\_call** → `firestore_list_collections`. Run it to confirm project, credentials, and database access.
  </Step>
</Steps>

See [Authentication](/integrations/authentication) for binding connections to MCP instances.

## What you can build

* **Webhook to Firestore** — Inbound event → `firestore_add_documents` append audit log → branch on document fields.
* **User profile sync** — Auth provider webhook → `firestore_update_document` merge profile fields with `update_mask`.
* **Rules CI check** — PR webhook delivers rules source → `firestore_validate_rules` → fail build when `valid` is false.
* **Ops dashboard** — `firestore_query_collection` filtered by status → LLM summary → scheduled email digest.

## Tools

| Tool                         | Description                                                                     |
| ---------------------------- | ------------------------------------------------------------------------------- |
| `firestore_get_documents`    | Fetch Firestore documents by path                                               |
| `firestore_query_collection` | Query a Firestore collection with optional filters and ordering                 |
| `firestore_add_documents`    | Add a document with an auto-generated ID to a Firestore collection              |
| `firestore_update_document`  | Update or merge fields on a Firestore document                                  |
| `firestore_delete_documents` | Delete Firestore documents by path                                              |
| `firestore_get_rules`        | Get the active Firestore security rules for the configured project and database |
| `firestore_validate_rules`   | Validate Firestore security rules source without deploying it                   |
| `firestore_list_collections` | List root Firestore collections or subcollections under a document path         |

## Example

Query open support tickets:

```json theme={null}
{
  "id": "open-tickets",
  "type": "mcp_call",
  "name": "Fetch open tickets",
  "tool_name": "firestore_query_collection",
  "tool_args": {
    "collection_path": "support_tickets",
    "filters": [
      {
        "field": "status",
        "op": "EQUAL",
        "value": "open"
      }
    ],
    "limit": 50
  },
  "timeout_s": 30
}
```

## Configuration

| Key                          | Required | Default     | Description                                                                                               |
| ---------------------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------- |
| `firestore_project_id`       | Yes      | —           | Google Cloud project ID that owns the Firestore database                                                  |
| `firestore_database`         | No       | `(default)` | Firestore database ID                                                                                     |
| `firestore_credentials_json` | No       | —           | Service account JSON key contents or file path (`CredsJSON`); omit to use Application Default Credentials |

## Troubleshooting

| Issue                  | Fix                                                                                    |
| ---------------------- | -------------------------------------------------------------------------------------- |
| `Permission denied`    | Grant the service account Firestore roles on the project; confirm `ProjectID`          |
| Invalid credentials    | Re-upload `CredsJSON`; ensure the JSON is valid and the key is not disabled            |
| ADC not found          | Set `CredsJSON` explicitly, or configure workload identity / ADC on the connector host |
| Document not found     | Verify `document_path` and `collection_path` are relative to the configured database   |
| Query requires index   | Create the composite index Firestore suggests in the error message                     |
| Rules validation fails | Read `issues` output; fix syntax and type errors before deploying                      |

## Related

* [Integrations quickstart](/integrations/quickstart)
* [MongoDB connector](/connectors/mongodb) — document database alternative
* [Postgres connector](/connectors/postgres) — relational reporting alongside Firestore app data
* [Connector catalog](/integrations/connector-catalog)
* [Troubleshooting](/platform/troubleshooting)