Skip to content

Installation Guide

Jump to bottom
jmrGrav edited this page Aug 2, 2026 · 3 revisions

Installation Guide

mcp-hugo-server-go runs in two transport modes, built from the same binary. They serve different purposes — pick based on who you are, not which one sounds more advanced.

Remote HTTP + OAuth Local stdio
Who it's for Multi-user / shared instance (this project's own mcp.arleo.eu) One person editing their own Hugo site
Auth OAuth 2.1, read/write scopes None — stdio's whole premise is a trusted local single-user process
Setup cost Reverse proxy, TLS cert, OAuth client registration Download a binary (or npx), point it at your site
Install methods Self-hosted only npx, npm global install, or a .mcpb desktop extension (planned, not yet published)

Both modes are documented in the main repository README's ## Installation and ## Privacy policy sections — this page goes one level deeper operationally, and covers the same two production configs referenced elsewhere in this wiki (Live Deployment Runbook, OAuth Clients and Scopes).

Remote HTTP + OAuth (the arleo.eu config)

This is what backs https://mcp.arleo.eu/mcp — see Live Deployment Runbook for the full deploy pipeline and OAuth Clients and Scopes for client registration. Summary for a fresh self-hosted instance:

  1. Build or download the linux/amd64 binary.
  2. Write a config.yaml with transport: http, oauth.enabled: true, site_root pointed at your Hugo build output (not your project root — site_root must be the public/ directory Hugo builds into, not hugo_root itself; see Pitfall Anonymous vs Authenticated Server for a related scope-boundary pitfall and the operator guide's site_root field description for why this specific mistake silently ingests raw theme templates as content).
  3. Put a TLS-terminating reverse proxy in front of it (production uses OpenResty — see docs/examples/agent-ready/openresty-mcp.arleo.eu.conf for a reference vhost).
  4. Register OAuth clients per OAuth Clients and Scopes — read is self-serve DCR, write requires a registered client with a secret.
  5. Point MCP clients (Claude.ai, Claude Desktop, ChatGPT, Le Chat) at https://your-host/mcp per Client Compatibility.

This mode is unaffected by anything in the stdio/npx section below — the two transports share only the underlying tool implementations, not any runtime state or code path (server.New vs server.NewStdio, see the repository's internal/server/server.go).

Local stdio (single-user desktop use)

No OAuth, no reverse proxy, no TLS. The client (Claude Desktop, or any MCP host that can launch a local subprocess) spawns the binary directly and talks JSON-RPC over stdin/stdout. Write access is granted unconditionally over this transport — that is deliberate, not an oversight: stdio's entire premise is a trusted local single-user process, and a read-only bundle couldn't do what this distribution channel exists for (create/update/publish content on your own site).

Option A — npx / npm

npx @jmrgrav/mcp-hugo-server-go
# or install globally:
npm install -g @jmrgrav/mcp-hugo-server-go

This is a thin wrapper (esbuild/ripgrep pattern, npm/ in the repository) — npm install downloads the real Go binary matching the package's version from GitHub Releases and verifies its SHA-256 checksum against the release's checksums.txt. No Go toolchain needed on the machine running it.

Configuration, since there's no config.yaml in an npx context, is via environment variables:

MCP_HUGO_SITE_ROOT=/path/to/your/hugo-site/public \
MCP_HUGO_HUGO_ROOT=/path/to/your/hugo-site \
MCP_HUGO_CONTENT_ROOT=/path/to/your/hugo-site/content \
MCP_HUGO_SITE_URL=https://your-site.example.com \
npx @jmrgrav/mcp-hugo-server-go

A config.yaml file, if you have one, takes precedence — env vars only fill in fields the file (or its absence) leaves empty.

Option B — direct binary download

Download the release asset matching your OS/arch from GitHub Releases (mcp-hugo-server-go_<os>_<arch>, e.g. mcp-hugo-server-go_darwin_arm64, mcp-hugo-server-go_windows_amd64.exe), then run it with either MCP_HUGO_SERVER_CONFIG=/path/to/config.yaml pointing at a file with transport: stdio, or the same MCP_HUGO_* env vars as above.

Option C — MCPB desktop extension

Planned but not yet published to the Claude Connectors Directory. The manifest (manifest.json in the repository root) is drafted and tested (manifest_test.go), including a 512×512 icon, but packing/submission hasn't happened yet — see the tracking issue for current status.

Verifying it works

A minimal end-to-end check (real initialize → tools/list → tools/call, no client UI needed) is what the repository's own cmd/mcp-hugo-server-go/stdio_integration_test.go does in CI. If you're debugging a local install, the same shape of check — spawn the binary/npx command as a subprocess, send an initialize request, then tools/list — will tell you whether the process is even reachable over stdio before troubleshooting anything site-specific.

Which one should I use?

  • Editing your own site from your own machine, one person: stdio via npx. Lowest setup cost, matches most people's actual use case.
  • Running a shared instance multiple people/agents connect to remotely, or you specifically want OAuth-scoped access control: HTTP + OAuth, self-hosted per the steps above.
  • Not sure: start with stdio/npx. Moving to HTTP+OAuth later doesn't require re-architecting anything — it's the same binary, same tool implementations, just a different launch mode and config.

Clone this wiki locally