Grav MCP Server: connect Claude.ai to your website in 30 minutes

⚡ In short

Connect Claude.ai to your Grav website in 30 minutes: a PHP plugin exposes 9 tools (read, create, update, delete pages, manage plugins) via JSON-RPC 2.0, a FastAPI proxy handles OAuth 2.1 authentication, and nginx bridges the internet to your server. Result: Claude can read and modify your site content directly from a conversation.

Code available on GitHub:

• 🔌 Grav plugin: jmrGrav/grav-plugin-mcp-server
• 🔐 OAuth proxy: jmrGrav/mcp-oauth-proxy

🧠 Why

Anthropic’s MCP (Model Context Protocol) allows Claude.ai to connect to external data sources via standardized tools. Until now, no MCP plugin existed for Grav CMS.

This homemade stack enables you to:

• Read and modify pages directly from Claude.ai without opening the Grav admin
• Automate bilingual content creation (FR + EN) in a single conversation
• Trigger actions on the site (clear cache, enable/disable plugins) by simple instruction
• Chain tools: create a page → IndexNow + Google Indexing trigger automatically

🔧 What was done

🏗️ Global architecture

        Claude.ai
            │
            │ HTTPS (OAuth 2.1 + PKCE)
            ▼
    ┌───────────────┐
    │  Cloudflare   │  WAF + Cache
    └───────┬───────┘
            │
            ▼
    ┌───────────────┐
    │     nginx     │  SSL termination
    │  mcp.site.com │  location /mcp → proxy
    └───────┬───────┘
            │
            ▼
    ┌───────────────┐
    │ FastAPI proxy │  Port 8083
    │  OAuth 2.1    │  Token validation
    │  mcp-proxy    │  SHA-256 hashing
    └───────┬───────┘
            │
            ▼
    ┌───────────────┐
    │  Grav plugin  │  Port 8090 (internal)
    │  JSON-RPC 2.0 │  9 MCP tools
    │  PHP 8.3      │
    └───────────────┘

📦 Components

🔌 Step 1 — Install the Grav plugin

# Clone the plugin
git clone https://github.com/jmrGrav/grav-plugin-mcp-server.git \
  /var/www/grav/user/plugins/mcp-server

# Permissions
sudo chown -R www-data:www-data /var/www/grav/user/plugins/mcp-server

# Clear Grav cache
cd /var/www/grav && sudo -u www-data php bin/grav clearcache

Add the internal vhost to your nginx Grav config:

# Internal MCP vhost — accessible only from the proxy
server {
    listen 127.0.0.1:8090;
    server_name localhost;
    root /var/www/grav;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # Block direct access to the PHP plugin
    location ^~ /api/mcp {
        return 444;
    }
}

🔐 Step 2 — Install the OAuth proxy

# Clone the proxy
git clone https://github.com/jmrGrav/mcp-oauth-proxy.git \
  /opt/mcp-oauth-proxy

# Create dedicated user
sudo useradd -r -s /bin/false mcp-proxy

# Create Python virtual environment
cd /opt/mcp-oauth-proxy
python3 -m venv venv
venv/bin/pip install -r requirements.txt

# Configure secrets
sudo mkdir -p /etc/mcp-oauth-proxy
sudo cp secrets.env.example /etc/mcp-oauth-proxy/secrets.env
sudo nano /etc/mcp-oauth-proxy/secrets.env
# → Fill in MCP_CLIENT_ID, MCP_CLIENT_SECRET, MCP_TOKEN_SECRET

# Install systemd service
sudo cp systemd/mcp-oauth-proxy.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now mcp-oauth-proxy

# Verify
sudo systemctl status mcp-oauth-proxy

🌐 Step 3 — Configure nginx

# Copy the vhost template
sudo cp nginx/mcp-vhost.conf /etc/nginx/sites-available/mcp
# Update your-domain.com and SSL paths
sudo nano /etc/nginx/sites-available/mcp

# Enable the vhost
sudo ln -s /etc/nginx/sites-available/mcp /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

🤝 Step 4 — Connect Claude.ai

1. Go to claude.ai → Settings → Connectors
2. Click Add connector
3. Enter the URL: https://mcp.your-domain.com/mcp
4. Follow the OAuth flow — authorize access
5. The 9 tools appear in the connectors list ✅

🛠️ The 9 available tools

🔒 Security

The proxy implements several layers of protection:

• OAuth 2.1 + PKCE S256 — secure authentication flow compliant with RFC 9728
• SHA-256 token hashing — tokens are never stored in plain text
• Atomic JSON writes — no state file corruption
• Systemd hardening — NoNewPrivileges, ProtectSystem=strict, IPAddressDeny=any, MemoryDenyWriteExecute
• nginx — direct access to the PHP plugin blocked (location ^~ /api/mcp { return 444; })

🏁 Conclusion

This stack turns Grav CMS into an active context source for Claude.ai — read, write, manage your site by simple conversation. The whole thing is reproducible on any nginx server with Python 3.11+, and the code is fully available on GitHub under the MIT license.

To go further:

• 💡 Add more MCP tools: media management, user management, system configuration
• 💡 Implement a per-tool permission system to restrict actions based on the OAuth token