Gopher & Gemini MCP Server

A modern, cross-platform Model Context Protocol (MCP) server that enables AI assistants to browse and interact with both Gopher protocol and Gemini protocol resources safely and efficiently.

Overview

The Gopher & Gemini MCP Server bridges vintage and modern alternative internet protocols with AI assistants, allowing LLMs like Claude to explore the unique content and communities that thrive on both Gopherspace and Geminispace. Built with FastMCP and modern Python practices, it provides secure, efficient gateways to these distinctive internet protocols.

Key Benefits:

• Discover alternative internet content - Access unique resources on both Gopher and Gemini protocols
• Safe exploration - Built-in security safeguards, TLS encryption, and content filtering
• Modern implementation - Uses FastMCP framework with async/await patterns
• Developer-friendly - Comprehensive testing, type hints, and documentation
• Advanced security - TOFU certificate validation and client certificate support for Gemini

Features

• Dual Protocol Support: gopher_fetch and gemini_fetch tools for comprehensive protocol coverage
• Comprehensive Gopher Support: Every standard RFC 1436 item type — menus (1) and Index-Search servers (7) as structured menus, text (0), HTML (h), info (i) and error (3) lines as text, the fourteen binary types as metadata only, and the three interactive ones (2, 8, T) refused without opening a connection. The one standard type with no category of its own is + (redundant server), which names an alternate host for the preceding item rather than content to render; it takes the unknown-type path below. An unknown type is read as text, best-effort, and an hURL URL:<target> selector is followed to the destination the server actually stated
• Full Gemini Implementation: Native gemtext parsing, TLS security, and status code handling
• Advanced Security: TOFU certificate validation with dedicated inspection and recovery tools, scoped client certificates, and secure TLS connections
• Safety First: Built-in timeouts, size limits, input sanitization, SSRF protection, per-host rate limiting, and host allowlists
• LLM-Optimized: Returns structured JSON responses designed for AI consumption
• Cross-Platform: Works seamlessly on Windows, macOS, and Linux
• Modern Development: Full type checking, linting, testing, and CI/CD pipeline
• High Performance: Async/await patterns with intelligent caching — and cached results say so, with a per-request refresh bypass
• Continuable Reads: A menu or page cut at the render limit reports where it stops, so offset reads the rest instead of leaving a partial view

Protocols in scope

Gopher (RFC 1436, including the de-facto item types in common use) and Gemini, both read-only. That is the whole surface, and the neighbouring protocols are deliberately out of scope rather than merely unbuilt:

• Titan and Misfin are write protocols — upload and mail. A tool an LLM drives should not be able to publish to someone's capsule or send mail as them, and adding either would make every safeguard here (robots, rate limits, allowlists) protect a much smaller share of what the tool can do.
• Spartan and Nex are separate protocols with their own parsers and their own failure modes, serving a small fraction of the hosts these two do. They would double the security-relevant surface for a rounding error in reach.
• Gopher+ is not implemented. The : item type is recognised because it appears in ordinary menus, but no Gopher+ attribute or metadata request is ever sent.

If you need one of these, an MCP server that does it well is a better answer than a flag on this one.

Documentation

Complete documentation is available at cameronrye.github.io/gopher-mcp

• Installation Guide
• Configuration Guide
• API Reference
• AI Assistant Guide
• Migration Guide and Changelog — what changed, and what an upgrade asks of you

Quick Start

Prerequisites

• Python 3.11+ - Download here
• uv package manager - Install uv

Installation

Option 1: Zero-install with uvx (Recommended)

No clone, no checkout — uv fetches and runs the published package on demand:

uvx gopher-mcp

Option 2: PyPI Installation

# Install from PyPI
pip install gopher-mcp

# Or with uv
uv add gopher-mcp

Option 3: Development Installation

# Clone the repository
git clone https://github.com/cameronrye/gopher-mcp.git
cd gopher-mcp

# Set up development environment
./scripts/dev-setup.sh  # Unix/macOS
# or
scripts\dev-setup.bat   # Windows

# Run the server
uv run task serve

Option 4: Docker

Tagged releases publish a slim, non-root image to ghcr.io/cameronrye/gopher-mcp, tagged with the release version plus :latest for stable (non-pre-release) tags:

# The default CMD serves streamable-http on 0.0.0.0:8000
docker run --rm -p 8000:8000 \
  -v gopher-mcp-state:/home/app/.local/share/gopher-mcp \
  ghcr.io/cameronrye/gopher-mcp:latest

# Or run over stdio, e.g. for an MCP client
docker run --rm -i --no-healthcheck \
  -v gopher-mcp-state:/home/app/.local/share/gopher-mcp \
  ghcr.io/cameronrye/gopher-mcp:latest --transport stdio

To run a modified tree, the repository ships the Dockerfile the published image is built from: docker build -t gopher-mcp .

Mount a volume, or Gemini trust is meaningless. Without one, the TOFU pins and the client certificates' private keys die with the container, so every start re-arms blind trust-on-first-use — the pin is the only thing that authenticates a Gemini capsule — and destroys any identity you minted, whose private key cannot be recovered.

Mount it at that exact path. /home/app/.local/share/gopher-mcp is where the server writes (tofu.json and certs/), and it is the one directory the image pre-creates owned by the runtime user and mode 700 — which is what lets a named volume come up writable instead of root-owned. Mounting anywhere else persists an empty directory. ~/.gemini is not the path: it is only a read-in-place upgrade route for installs that pinned certificates before gopher-mcp had a directory of its own, and it is honoured only when its store file is already there, which it never is in a fresh image.

Health checks. The HTTP transports serve GET /health, which answers {"status": "ok", "version": "..."} and nothing else — no configuration, no allowlists, no store paths. It bypasses authorization by SDK design, which is what makes it usable as a probe. The image's HEALTHCHECK polls it on the hard-coded port 8000 to match the default CMD, so override the healthcheck alongside --port, and pass --no-healthcheck when running stdio — a stdio container serves no HTTP and would otherwise be reported unhealthy while working perfectly.

Note: the default CMD binds 0.0.0.0 so the container is reachable out of the box. A non-loopback --host also turns off FastMCP's DNS-rebinding Host/Origin check, matching what the SDK does when it is constructed with such a host — otherwise every client that was not on localhost got 421 Misdirected Request. Keep the check on by naming the hostnames the deployment answers to with --allowed-host NAME (repeatable; a bare name matches any port). The HTTP transports are unauthenticated and have no TLS either — put the container behind a trusted reverse proxy, or use --transport stdio, before exposing it beyond your machine.

MCP Client Integration

Every client below runs the server over stdio — no ports, no TLS, no listening socket. The entry is the same three fields everywhere; only the file and the top-level key change: