Building Astro sites with AI tools

Reference this doc to your favorite AI assistantChatGPT Claude DeepSeek Google AI mode Gemini Perplexity Mistral Grok

Ask your question and get a summary of the document by referencing this page and the AI provider of your choice

Edit this doc

If you have an idea for improving this documentation, please feel free to contribute by submitting a pull request on GitHub.

GitHub link to the documentation

Copy

Copy doc Markdown to clipboard

import { Steps, LinkButton, Card, Tabs, TabItem } from '@astrojs/starlight/components';

AI-powered editors and agentic coding tools generally have good knowledge of Astro's core APIs and concepts. However, some may use older APIs and may not be aware of newer features or recent changes to the framework.

This guide covers how to enhance AI tools with up-to-date Astro knowledge and provides best practices for building Astro sites with AI assistance.

Context files

Astro provides llms.txt and llms-full.txt files that contains the full docs content in a format optimized for AI consumption. These are static files of the Astro Docs content in a streamlined Markdown format. Some AI tools can auto-discover these files if you provide https://docs.astro.build as a docs source.

While these files provide a minimal, easy-to-parse version of Astro's documentation, they are large files that will use a lot of tokens if used directly in context and will need to be updated regularly to stay current. They are best used as a fallback when the AI tool does not have access to the latest documentation in other ways. The MCP server provides more efficient access to the full documentation with real-time search capabilities, making it the preferred option when available.

Astro Docs MCP Server

You can ensure your AI tools have current Astro knowledge through the Astro Docs MCP (Model Context Protocol) server. This provides real-time access to the latest documentation, helping AI tools avoid outdated recommendations and ensuring they understand current best practices.

:::tip[What is MCP?] Model Context Protocol (MCP) is a standardized way for AI tools to access external tools and data sources. :::

Unlike AI models trained on static data, the MCP server provides access to the latest Astro documentation. The server is free, open-source, and runs remotely with nothing to install locally.

The Astro Docs MCP server uses the kapa.ai API to maintain an up-to-date index of the Astro documentation.

Server Details

Name: Astro Docs
URL: https://mcp.docs.astro.build/mcp
Transport: Streamable HTTP

Installation

The setup process varies depending on your AI development tool. You may see some tools refer to MCP servers as connectors, adapters, extensions, or plugins.

Manual setup

Many tools support a common JSON configuration format for MCP servers. If there are not specific instructions for your chosen tool, you may be able to add the Astro Docs MCP server by including the following configuration in your tool's MCP settings:

Claude Code is an agentic coding tool that runs on the command line. Enabling the Astro Docs MCP server allows it to access the latest documentation while generating Astro code.

Install using the terminal command:

shell

Copy code

Copy the code to the clipboard

claude mcp add --transport http astro-docs https://mcp.docs.astro.build/mcp

More info on using MCP servers with Claude Code

Claude Code GitHub Action

Claude Code also provides a GitHub Action that can be used to run commands in response to GitHub events. Enabling the Astro Docs MCP server allows it to access the latest documentation while answering questions in comments or generating Astro code.

You can configure it to use the Astro Docs MCP server for documentation access by adding the following to the workflow file:

yaml

Copy code

Copy the code to the clipboard

# ...rest of your workflow configuration- uses: anthropics/claude-code-action@beta  with:    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}    mcp_config: |      {        "mcpServers": {          "astro-docs": {            "type": "http",            "url": "https://mcp.docs.astro.build/mcp"          }        }      }    allowed_tools: "mcp__astro-docs__search_astro_docs"

More info on using MCP servers with the Claude Code GitHub Action

Cursor

Cursor is an AI code editor. Adding the Astro Docs MCP server allows Cursor to access the latest Astro documentation while performing development tasks.

Install by clicking the button below:

Add to Cursor

More info on using MCP servers with Cursor

Visual Studio Code

Visual Studio Code supports MCP servers when using Copilot Chat. Adding the Astro Docs MCP server allows VS Code to access the latest Astro documentation when answering questions or performing coding tasks.

Install by clicking the button below:

Add to VS Code

More info on using MCP servers with VS Code

Warp

Warp (formerly Warp Terminal) is an agent development environment built for coding with multiple AI agents. Adding the Astro Docs MCP server allows Warp to access the latest Astro documentation when answering questions or performing coding tasks.

Open your Warp settings and go to AI > MCP Servers > Manage MCP Servers.
Click "Add".

Enter the following configuration. You can optionally configure the Astro MCP server to activate on startup using the start_on_launch flag:

json

Copy code

Copy the code to the clipboard

{  "mcpServers": {    "Astro docs": {      "command": "npx",      "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"],      "env": {},      "working_directory": null,      "start_on_launch": true    }  }}

Click "Save".

More info on using MCP servers with Warp

Claude.ai / Claude Desktop

Claude.ai is a general-purpose AI assistant. Adding the Astro Docs MCP server allows it to access the latest documentation when answering Astro questions or generating Astro code.

Navigate to the Claude.ai connector settings.
Click "Add custom connector". You may need to scroll down to find this option.
Enter the server URL: https://mcp.docs.astro.build/mcp.
Set the name to "Astro docs".

More info on using MCP servers with Claude.ai

Windsurf

Windsurf is an AI-powered agentic coding tool, available as editor plugins or a standalone editor. It can use the Astro Docs MCP server to access documentation while performing coding tasks.

Windsurf doesn't support streaming HTTP, so it requires a local proxy configuration:

Open ~/.codeium/windsurf/mcp_config.json in your editor.

Add the following configuration to your Windsurf MCP settings:

json

Copy code

Copy the code to the clipboard

{  "mcpServers": {    "Astro docs": {      "command": "npx",      "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]    }  }}

Save the configuration and restart Windsurf.

More info on using MCP servers with Windsurf

Gemini CLI

Gemini CLI is a command-line AI coding tool that can use the Astro Docs MCP server to access documentation while generating Astro code.

You can configure MCP servers at the global level in the ~/.gemini/settings.json file, or in a .gemini/settings.json file in a project root.

json

Copy code

Copy the code to the clipboard

{  "mcpServers": {    "Astro docs": {      "httpUrl": "https://mcp.docs.astro.build/mcp",    }  }}

More info on using MCP servers with Gemini CLI

Zed

Zed supports MCP servers when using its AI capabilities. It can use the Astro Docs MCP server to access documentation while performing coding tasks.

Zed doesn't support streaming HTTP, so it requires a local proxy configuration:

Open ~/.config/zed/settings.json in your editor.

Add the following configuration to your Zed MCP settings:

json

Copy code

Copy the code to the clipboard

{  "context_servers": {    "Astro docs": {      "command": "npx",      "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]    }  }}

Save the configuration.

More info on using MCP servers with Zed

ChatGPT

:::caution[Limited availability] MCP server integration is only available for ChatGPT Pro, Team, and Enterprise users. The setup process is more complex than other tools. :::

Refer to the OpenAI MCP documentation for specific setup instructions.

Raycast

Raycast can connect to MCP servers to enhance its AI capabilities. AI features such as MCP require a Raycast Pro account, so ensure you have upgraded before trying to install. Adding the Astro Docs MCP server allows Raycast to access the latest Astro documentation while answering questions.

Install by clicking the button below:

Add to Raycast

More info on using MCP servers with Raycast

Usage

Once configured, you can ask your AI tool questions about Astro, and it will retrieve information directly from the latest docs. Coding agents will be able to consult the latest documentation when performing coding tasks, and chatbots will be able to accurately answer questions about Astro features, APIs, and best practices.

:::note[Remember] The Astro Docs MCP server provides access to current documentation, but your AI tools are still responsible for interpretation and code generation. AI makes mistakes, so always review generated code carefully and test thoroughly. :::

Troubleshooting

If you encounter issues:

Verify that your tool supports streamable HTTP transport.
Check that the server URL is correct: https://mcp.docs.astro.build/mcp.
Ensure your tool has proper internet access.
Consult your specific tool's MCP integration documentation.

If you are still having problems, open an issue in the Astro Docs MCP Server repository.

Discord AI Support

The same technology that powers Astro's MCP server is also available as a chatbot in the Astro Discord for self-serve support. Visit the #support-ai channel to ask questions about Astro or your project code in natural language. Your conversation is automatically threaded, and you can ask an unlimited number of follow-up questions.

Conversations with the chatbot are public, and are subject to the same server rules for language and behavior as the rest of our channels, but they are not actively visited by our volunteer support members. For assistance from the community, please create a thread in our regular #support channel.

Tips for AI-Powered Astro Development

Start with templates: Rather than building from scratch, ask AI tools to start with an existing Astro template or use npm create astro@latest with a template option.
Use astro add for integrations: Ask AI tools to use astro add for official integrations (e.g. astro add tailwind, astro add react). For other packages, install using the command for your preferred package manager rather than editing package.json directly.
Verify current APIs: AI tools may use outdated patterns. Ask them to check the latest documentation, especially for newer features like sessions and actions. This is also important for features that have seen significant changes since their initial launch, such as content collections, or previously experimental features that may no longer be experimental.
Use project rules: If your AI tool supports it, set up project rules to enforce best practices and coding standards, such as the ones listed above.

Authentication

Client-side Scripts