@firecms/mcp-server

MCP server for FireCMS Cloud. Lets AI assistants connect a Firebase project to FireCMS, infer collections from the data already in Firestore, and then manage the CMS — browse and edit data, shape collection schemas and properties, configure the project, and manage users.

Admin-only: All write operations require the authenticated user to have the admin role on the target project. Read operations are available to any authenticated project member. Onboarding tools run before a project exists, so they are gated by Google Cloud access instead.

The same server runs in two places:

• Hosted, at https://api.firecms.co/mcp, for everyone. Clients sign in with OAuth in the browser; nothing to install. It holds no Google Cloud credentials, so connecting a new Firebase project is handed off to the web app. The FireCMS backend mounts it through the @firecms/mcp-server/hosted entry point.
• Local, over stdio (npx @firecms/mcp-server). It signs in with your Google account (firecms_login), so it can also enable APIs, create Firestore databases and connect projects end to end.

Hosted server

In Claude (claude.ai or Claude Desktop): Settings → Connectors → Add custom connector, and paste https://api.firecms.co/mcp.

In Claude Code:

claude mcp add --transport http firecms https://api.firecms.co/mcp

Any other client that takes remote servers by URL:

{
  "mcpServers": {
    "firecms": { "url": "https://api.firecms.co/mcp" }
  }
}

Local server

Setup

cd packages/mcp_server && npm install && npm run build

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "firecms": {
      "command": "node",
      "args": ["/path/to/packages/mcp_server/dist/cli.js"]
    }
  }
}

Or use npx (no build required):

{
  "mcpServers": {
    "firecms": {
      "command": "npx",
      "args": ["@firecms/mcp-server"]
    }
  }
}

Use firecms_login to sign in when prompted. Tokens are shared with the FireCMS CLI (~/.firecms/tokens.json).

Connecting an existing Firebase project

The typical first session. Everything here is driven by the Google account you logged in with.

1. list_firebase_projects        → see which projects you can connect, and what they still need
2. get_project_setup_status      → check one project in detail (optional)
3. enable_project_apis           → only if apisEnabled is false
4. enable_firestore              → only if firestoreEnabled is false (location is permanent)
5. connect_project_to_firecms    → service account, admin user, and the security rules
6. setup_all_collections         → infer every root collection from the existing data

Firebase Authentication must be enabled on the project before step 5 — it is the one prerequisite with no API, so turn it on in the Firebase console. Step 5 then adds FireCMS's access rule to the project's Firestore and Storage rules; without it the CMS reports "Missing Firestore Security Rules" and opens nothing, and no tool here would notice, because they all read through the backend's service account, which bypasses security rules.

Step 6 is where an existing project becomes a working CMS: FireCMS samples the documents at each root collection, infers the property types, and uses an LLM to pick display names, a singular name, an icon and a navigation group.

Building collections from existing data

| Tool | Description | |------|-------------| | get_root_collections | List the Firestore root collections of a project (read live) | | list_subcollections | List the subcollections of a document, to explore nested data | | list_databases | List Firestore databases (only needed beyond (default)) | | preview_inferred_schema | Infer a schema from sampled documents without saving | | infer_collections_from_data 🔒 | Infer and save collections for chosen paths | | setup_all_collections 🔒 | Infer and save every unmapped root collection |

preview_inferred_schema is the non-destructive option: it samples up to 200 documents, infers types, enums and validation locally, and hands back a draft you can edit and then persist with save_collection_schema. It also works for subcollections and any path the bulk tools skip.

infer_collections_from_data and setup_all_collections go through the backend, which adds the LLM pass and writes the result straight into the project. Both skip paths that already map to a collection, so they are safe to re-run as the database grows.

Tools

Auth

| Tool | Description | |------|-------------| | firecms_login 💻 | Sign in via browser (Google OAuth) | | firecms_logout 💻 | Sign out | | firecms_get_current_user | Show current user |

Onboarding

| Tool | Description | |------|-------------| | list_firebase_projects 💻 | Google Cloud projects you can access, with FireCMS readiness flags | | get_project_setup_status 💻 | Detailed readiness of one project | | list_firestore_locations 💻 | Locations available for a new Firestore database | | enable_project_apis 💻 | Enable the Google Cloud APIs FireCMS requires | | enable_firestore 💻 | Create the default Firestore database (location is permanent) | | connect_project_to_firecms | Connect an existing Firebase project, and apply the security rules it needs. Hosted: returns the link to connect it in the web app | | apply_firestore_security_rules 🔒 | Add FireCMS's access rule to Firestore and Storage (idempotent) | | create_firecms_webapp 🔒 | Retry web app creation if it failed during connect |

Projects & Root Collections

| Tool | Description | |------|-------------| | list_projects | List FireCMS Cloud projects | | get_root_collections | List Firestore root collections | | list_subcollections | List the subcollections of a document |

Project Configuration 🔒

| Tool | Description | |------|-------------| | get_project_config | Get full project config (name, colors, plan, features) | | update_project_name | Rename a project | | update_project_colors | Update primary/secondary brand colors | | update_default_locale | Change the default locale | | toggle_text_search | Enable/disable local text search | | toggle_entity_history | Enable/disable entity history tracking |

Users 🔒

| Tool | Description | |------|-------------| | list_users | List project users and roles | | add_user | Invite a user | | update_user_roles | Change user roles | | remove_user | Remove a user |

Collection Schemas 🔒

| Tool | Description | |------|-------------| | list_collection_schemas | List all persisted collection schemas | | get_collection_schema | Get full schema for a collection | | save_collection_schema | Create or replace a collection schema | | update_collection_schema | Partially update a collection schema | | delete_collection_schema | Delete a collection schema (data untouched) | | save_property | Add or update a single property in a collection | | delete_property | Remove a property from a collection schema |

AI Schema Generation

| Tool | Description | |------|-------------| | generate_collection | AI-generate a collection schema from a prompt | | modify_collection | AI-modify an existing schema from a prompt |

Documents (Firestore CRUD)

| Tool | Description | |------|-------------| | list_documents | Query documents (filters, ordering, pagination) | | get_document | Get a document by path | | create_document | Create a new document | | update_document | Partial update of a document | | delete_document | Delete a document | | count_documents | Count documents in a collection |

Data Import & Export

| Tool | Description | |------|-------------| | export_collection | Export collection data as JSON | | import_documents 🔒 | Bulk import documents (max 500/call) |

🔒 = Admin-only operation · 💻 = local server only

Every tool declares a title and a readOnlyHint, plus a destructiveHint when it writes: false for tools that only add (create a document, invite a user), true for anything that can overwrite or delete.

Resources

| URI | Description | |-----|-------------| | firecms://projects/{id}/collections | Firestore root-level collections | | firecms://projects/{id}/users | Project users and roles | | firecms://projects/{id}/schemas | All collection schemas (full config tree) | | firecms://projects/{id}/config | Project configuration snapshot |

Example Workflows

Bring an existing Firebase project into FireCMS

1. list_firebase_projects        → pick a project that is not yet connected
2. connect_project_to_firecms    → provision it
3. setup_all_collections         → infer collections from the data already there

Create a collection from scratch

1. firecms_login          → authenticate
2. list_projects          → pick your project
3. save_collection_schema → define the schema
4. import_documents       → seed with initial data

Shape a schema before committing to it

1. preview_inferred_schema  → draft a schema from real documents, nothing saved
2. save_property            → adjust individual fields
3. save_collection_schema   → persist the result

AI-assisted schema creation

1. generate_collection    → describe what you want in natural language
2. save_collection_schema → persist the generated schema

Architecture

Sessions: local and hosted

Nothing reads credentials from process-wide state. Every API call goes through a FireCMSSession (session.ts) — the user's email, a Firebase ID token on firecms-backend, and a Google access token when there is one — passed to createFireCMSMcpServer():

• Local (cli.ts): localSession reads the CLI's tokens file and exchanges the Google ID token for a backend token (below). The login/logout tools are registered by the CLI only.
• Hosted (hosted.ts): the backend resolves each request's OAuth bearer token to a user and passes a session that mints that user's backend ID token. There is no Google token, so the Google Cloud tools are replaced by a connect_project_to_firecms that links to the web app. Every request gets its own server and transport (stateless Streamable HTTP), so nothing of one person's session outlives their request. hosted.ts never imports the CLI's login flow; a test walks its import graph to keep it that way.

Authentication

The FireCMS Cloud API expects two different tokens, and the server sends both — the same pair the web app sends:

| Header | Token | Used by | |--------|-------|---------| | Authorization | Firebase ID token issued by firecms-backend | endpoints gated by firebaseAuthorization() — most of the API | | x-admin-authorization | Google OAuth access token (cloud-platform scope) | endpoints gated by googleCloudAuthentication() — GCP provisioning. Local sessions only |

firecms login only produces the Google credentials. The Google ID token is not a Firebase ID token — it is issued by accounts.google.com for the Google OAuth client, so verifyIdToken() rejects it. backend-auth.ts therefore exchanges it for a real firecms-backend token through Identity Toolkit signInWithIdp, which is the headless equivalent of the web app's signInWithPopup(auth, GoogleAuthProvider). The exchanged token is cached in memory until shortly before it expires.

Where collection configurations live

FireCMS Cloud reads collection configurations from the backend Firestore, at projects/{projectId}/collections/{collectionId} — see useFirestoreCollectionsConfigController in FireCMSCloudApp.tsx. That is not the client project's __FIRECMS/config/collections, which is the self-hosted layout and is never read by Cloud.

The backend exposes no REST endpoints for that store — the web app writes to it directly with the Firebase SDK — so backend-firestore.ts talks to the Firestore REST API with the exchanged Firebase token. The backend's security rules apply unchanged.

Document CRUD is different: it is proxied by the backend into the client's Firestore using the project's delegated service account.

Cache-aware collection discovery

The backend's firestore_root_collections endpoint caches its answer for 5 minutes per project, so it misses collections created since the last lookup — including every collection of a project connected moments ago. Discovery therefore goes through the uncached admin/collections/list endpoint, and setup_all_collections resolves the paths itself rather than delegating to initial_setup, which resolves them through that same cache.

infer_collections_from_data also refuses paths with no documents. The backend runs its LLM pass regardless, and with nothing to sample the model invents a schema from the path name alone — an empty articles path yields plausible title/slug/status/author fields that exist nowhere in the data.

stdout is reserved

On a stdio transport, stdout carries the JSON-RPC stream, so cli.ts routes every console channel to stderr before starting. Dependencies do log — @firecms/schema_inference logs while inferring properties — and a single stray console.log would corrupt the protocol stream.

Security

• Hosted authentication: OAuth 2.1 with PKCE against the FireCMS backend; the person approves each client in the web app. The backend stores tokens only as hashes, rotates refresh tokens, and never holds Google Cloud credentials
• Local authentication: Google OAuth via browser, same as firecms login CLI
• Authorization: Write operations enforce admin role check per project
• Token storage: ~/.firecms/tokens.json (shared with CLI); the exchanged backend token is held in memory only and dropped on logout
• Admin cache: Role checks are cached for 5 minutes per project
• Credential hygiene: list_projects strips each project's service account from its output, so credentials are never serialised into the model's context