Skip to content

Installation Guide

Jump to bottom
Jm Rohmer edited this page Aug 20, 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/admin scopes (see OAuth Clients and 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 (download from GitHub Releases; Directory listing submitted, pending review)

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

  1. Download the .mcpb file attached to the latest release (built and attached automatically as part of the release pipeline, using .mcpbignore at the repo root to keep it scoped to just the manifest, icon, and the two platform binaries — not the whole repo).
  2. Double-click it, or in Claude Desktop: Settings → Extensions → drag the file in.
  3. Claude Desktop prompts for the same user_config fields as the env-var path above (site_root/hugo_root/content_root/site_url/site_name).

It's unsigned — mcpb sign --self-signed is currently broken in the upstream CLI (confirmed by direct testing: reports success but writes nothing to the file), so Claude Desktop will show an "unverified publisher" warning during install. That's expected, not a sign of a broken bundle. Submitted to the Claude Connectors Directory for review (Phase 5); not yet listed there, but fully installable manually via the steps above in the meantime.

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