Hugo MCP server

A generic MCP (Model Context Protocol) server for any Hugo blog, deployed on Cloudflare Workers.

It reads your blog's llms.txt and llms-full.txt files and exposes them as structured tools that AI assistants (Claude, Cursor, and others) can query to understand your content.

---

How it works

Your Hugo blog           Cloudflare Worker          AI assistant
─────────────────        ──────────────────         ──────────────
/llms.txt          ───►  /mcp  (MCP tools)  ◄───►  Claude / Cursor
/llms-full.txt     ───►  /llms.txt (proxy)          etc.
                         /llms-full.txt (proxy)

The Worker fetches your blog's llms.txt and llms-full.txt at runtime (with an in-memory cache), and exposes three MCP tools:

Tool	What it does
get_blog_summary	Returns the concise overview from /llms.txt
get_blog_full_index	Returns the full content index from /llms-full.txt
search_content	Searches for a keyword across the full index and returns matching paragraphs with context

---

Prerequisites

• A Hugo blog publicly accessible on the web
• llms.txt and llms-full.txt files in your Hugo static/ folder (see Step 1)
• A Cloudflare account (free tier is enough)
• Node.js ≥ 18
• Wrangler CLI (npm install -g wrangler)

---

Step 1 — Create your llms.txt files

llms.txt and llms-full.txt are plain-text files that describe your blog's content to language models. They live in your Hugo static/ folder and are served automatically at /llms.txt and /llms-full.txt.

Option A — Use the helper script

# Clone this repo
git clone https://github.com/your-username/hugo-llms-mcp.git
cd hugo-llms-mcp

# Edit the configuration at the top of the script
nano scripts/generate-llms.py

# Run it — outputs static/llms.txt and static/llms-full.txt
python3 scripts/generate-llms.py

Then copy the generated files to your Hugo site's static/ folder, review and enrich them manually, and redeploy your site.

Option B — Write them by hand

static/llms.txt (summary, ~50 lines):

# My Hugo Blog

> One-line tagline for your blog.

Author: Your Name
Site: https://your-hugo-blog.com
Language(s): English

## Description

Two or three sentences describing what the blog is about,
who the author is, and who it's for.

## Published content

- Post Title One (Month Year) — https://your-hugo-blog.com/posts/post-one/
- Post Title Two (Month Year) — https://your-hugo-blog.com/posts/post-two/

## Instructions for language models

- Content may be freely summarised with attribution and a link to the source.
- Short excerpts may be quoted for informational purposes.
- Reproduction of full articles is not permitted.

static/llms-full.txt (extended index, as long as needed):

# My Hugo Blog
# llms-full.txt — Extended index for language models

Site: https://your-hugo-blog.com
Author: Your Name
Generated: June 2026

---

## Author profile

A longer bio of the author.

---

## Content

---

### Post Title One

URL: https://your-hugo-blog.com/posts/post-one/
Date: January 2025
Description: A detailed summary of what this post covers,
key points made, people or places mentioned, and tone.

---

### Post Title Two

...

Tip: The more detailed llms-full.txt is, the more useful the search_content tool becomes. Include summaries, key locations, episode descriptions, and any cross-references between posts.

Verify the files are live

After deploying your Hugo site, check:

https://your-hugo-blog.com/llms.txt
https://your-hugo-blog.com/llms-full.txt

Both should return plain text. If they do, you're ready for Step 2.

---

Step 2 — Configure the Worker

Clone this repo (if you haven't already) and edit wrangler.toml:

name = "my-blog-mcp"            # becomes my-blog-mcp.<account>.workers.dev

[vars]
SITE_URL     = "https://your-hugo-blog.com"
SITE_NAME    = "My Hugo Blog"
CACHE_TTL_SEC = "3600"          # cache TTL in seconds; 0 = always fetch fresh

---

Step 3 — Deploy

# Install dependencies
npm install

# Log in to Cloudflare (once)
wrangler login

# Deploy
npm run deploy

Wrangler will print the Worker URL:

https://my-blog-mcp.<your-account>.workers.dev

---

Step 4 — Verify

# Health check
curl https://my-blog-mcp.<your-account>.workers.dev/health

# List MCP tools
curl -s -X POST https://my-blog-mcp.<your-account>.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python3 -m json.tool

# Search for a keyword
curl -s -X POST https://my-blog-mcp.<your-account>.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_content","arguments":{"query":"your keyword","max_results":3}}}' | python3 -m json.tool

---

Step 5 — Connect to Claude

Claude.ai

Settings → Connectors → Add MCP Server:

https://my-blog-mcp.<your-account>.workers.dev/mcp

Claude Desktop

Install the mcp-remote bridge (needed because Claude Desktop doesn't yet support remote MCP natively):

npm install -g mcp-remote

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "my-blog": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://my-blog-mcp.<your-account>.workers.dev/mcp"
      ]
    }
  }
}

Restart Claude Desktop. The three tools will appear in the tool list.

Cursor / other MCP clients

Use the Worker URL directly: https://my-blog-mcp.<your-account>.workers.dev/mcp

---

Updating content

The Worker fetches content from your live site and caches it in memory for CACHE_TTL_SEC seconds (default: 1 hour). So when you publish new posts:

1. Update llms.txt and llms-full.txt in your Hugo static/ folder.
2. Redeploy your Hugo site — the Worker will pick up the changes automatically within the cache TTL.

No need to redeploy the Worker itself unless you change wrangler.toml or src/index.js.

---

Project structure

hugo-llms-mcp/
├── src/
│   └── index.js          ← Cloudflare Worker (MCP server logic)
├── scripts/
│   └── generate-llms.py  ← Helper to scaffold llms.txt files
├── wrangler.toml         ← Cloudflare configuration (edit this)
├── package.json
├── .gitignore
├── LICENSE
└── README.md

---

Cloudflare free tier limits

Resource	Free limit
Requests	100,000 / day
CPU time	10 ms / request
Memory	128 MB
Script size	1 MB (compressed)

A typical blog MCP server uses well under all of these limits.

---

Real-world example

This project was originally built for ciclogravelista.com, a personal gravel cycling travel blog. The live MCP server is available at:

https://ciclogravelista-mcp.ciclogravelista.workers.dev/mcp

Source: github.com/your-username/ciclogravelista-mcp

---

License

MIT — see LICENSE.