Astro prerequisites

This page lists everything needed before any Astro tool will run. Astro sites are unusual compared to WordPress/Duda because the “content store” is a GitHub repo and the “publish trigger” is Cloudflare Pages auto-build on push.

1. The Astro project itself

You need an Astro project already set up and deployed once via Cloudflare Pages. The worker doesn’t scaffold Astro for you — it only writes .astro files into an existing project’s src/pages/ folder.

Minimum project shape:

my-astro-site/
├─ astro.config.mjs
├─ package.json
├─ src/
│  ├─ layouts/        (optional but common)
│  └─ pages/
│     └─ index.astro
└─ ...

If you’re starting from scratch, run npm create astro@latest locally, push to GitHub, then connect to Cloudflare Pages.

2. GitHub App installed on the repo

The worker writes to GitHub via a GitHub App (not a personal access token). One-time install:

1. Open /admin/github on the worker (super-admin only)
2. Click Install GitHub App → GitHub opens in a new tab
3. Choose the account or org that owns the repo
4. Pick Only select repositories → choose the Astro repo (or All repositories if you want)
5. Approve. You’ll be redirected back to /admin/github with the new installation listed

After installation, the worker can read and write content in the selected repos. Other repos under the same account are not touched.

To add more repos later, click Add repos / re-auth on the installation row — that opens the GitHub installation settings page so you can tick extra repositories.

3. Cloudflare Pages project

In the Cloudflare dashboard:

1. Pages → Create a project → Connect to Git
2. Authorize Cloudflare to read your GitHub repo
3. Pick the Astro repo
4. Build settings:
   • Framework preset: Astro
   • Build command: npm run build (auto-filled)
   • Build output: dist (auto-filled)
   • Root directory: leave blank unless monorepo
5. Click Save and Deploy

After the first deploy, note the project’s:

• Slug — visible at dash.cloudflare.com/<account>/pages/view/<slug>. Used by the worker as cf_pages_project.
• Live URL — usually https://<slug>.pages.dev. Used by the worker as cf_pages_url.

4. Worker secrets — Cloudflare Pages API (optional)

The check_astro_deploy tool calls the Cloudflare Pages API to read build status. It’s optional — the worker hides it from tools/list when the secrets aren’t set, so Claude won’t try to call it.

To enable it:

1. dash.cloudflare.com → My Profile → API Tokens → Create Token
2. Custom token template
3. Permissions: Account → Cloudflare Pages → Edit
4. Set the resulting token + your account ID:

echo "<api_token>" | npx wrangler secret put CLOUDFLARE_API_TOKEN
echo "<account_id>" | npx wrangler secret put CLOUDFLARE_ACCOUNT_ID

Or via the Cloudflare dashboard → Worker → Variables and Secrets.

Without these, you can still create / update / list Astro routes — you just won’t get programmatic build-status feedback. You’ll need to refresh the Pages dashboard manually instead.

5. Site registered in /admin/sites

Required fields:

Field	Value
ID (slug)	Stable worker identifier — astro-site, marketing-site
Display name	Free text
Platform	astro (will show in the dropdown as “Astro — Cloudflare Pages”)
Base URL	Optional — Worker uses cf_pages_url for output URLs. Leave blank or set to your custom domain.
GitHub repo	<owner>/<repo> of the Astro repo (e.g. supportsn/marketing-site). Must be one the GitHub App can see.
GitHub branch	The branch Cloudflare Pages builds from. Usually main.
Astro project root	Path inside the repo where astro.config.mjs lives. Blank if root. Set if monorepo (e.g. apps/web).
Cloudflare Pages project	The CF Pages slug from step 3 (e.g. marketing-site)
Production URL	The live <slug>.pages.dev URL or your custom domain

WordPress fields (app password, builders, MCP backend) are hidden for Astro sites — they don’t apply.

6. Token scope

The MCP token must include:

• The Astro site in allowed_sites
• The Astro tools in allowed_tools:
  • create_astro_route — write a new route
  • update_astro_route — overwrite an existing route
  • list_astro_routes — list every .astro file in src/pages/**
  • check_astro_deploy — query CF Pages build status (only visible if you set the CF secrets in step 4)

Notably not in any regular-user token: delete_astro_route. That tool is filtered out of the token-create UI for regular users + refused at runtime if a regular-user token somehow has it in scope. Only super-admin tokens (issued via master path) can call it.

7. Verify

Two checks before running real workflow tools:

List sites and find the Astro one.

→ Returns your site with platform astro and the linked repo / project slug.

List Astro routes on marketing-site.

→ Returns every .astro file in src/pages/**. If you get E_GITHUB_NOT_INSTALLED, the GitHub App isn’t installed on the repo’s owner (go back to step 2). If you get an empty list but the repo has pages, check astro_project_root — the path is wrong.

Next

• Create a route
• Update a route
• Verify CF Pages build