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: Handles menus (type 1), text files (type 0), search servers (type 7), and binary files
• 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

Documentation

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

• Installation Guide
• API Reference
• Advanced Features
• AI Assistant Guide

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

The repository ships a Dockerfile that builds a wheel and installs it into a slim, non-root image. There is no published image — build it yourself:

docker build -t gopher-mcp .

# The default CMD serves streamable-http on 0.0.0.0:8000
docker run --rm -p 8000:8000 gopher-mcp

# Or run over stdio, e.g. for an MCP client
docker run --rm -i gopher-mcp --transport stdio

Note: the default CMD binds 0.0.0.0 so the container is reachable out of the box. The HTTP transports are unauthenticated and have no TLS — put the container behind a trusted reverse proxy, or use --transport stdio, before exposing it beyond your machine.

Claude Desktop Integration

Add to your claude_desktop_config.json. The recommended entry uses uvx, so no clone or local checkout is required:

{
  "mcpServers": {
    "gopher": {
      "command": "uvx",
      "args": ["gopher-mcp"],
      "env": {
        "GOPHER_MAX_RESPONSE_SIZE": "1048576",
        "GOPHER_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

{
  "mcpServers": {
    "gopher": {
      "command": "uv",
      "args": ["--directory", "/path/to/gopher-mcp", "run", "task", "serve"],
      "env": {
        "GOPHER_MAX_RESPONSE_SIZE": "1048576",
        "GOPHER_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

Cross-Platform Development

This project includes a unified Python-based task management system that works across all platforms:

Recommended (All Platforms)

python task.py <command>    # Unified Python task runner (recommended)

Alternative Options

# Unix/macOS/Linux
make <command>              # Traditional make (delegates to task.py)

# Universal fallback
uv run task <command>       # Direct taskipy usage

Available Commands

Usage

The server registers eight MCP tools:

The four fetch tools are annotated read-only and open-world. The four certificate tools never touch the network, and each pair is split read from write so a client can gate the destructive one on its own.

gopher_fetch Tool

Fetches Gopher menus, text files, or metadata by URL with comprehensive error handling and security safeguards.

Parameters:

• url (string, required): Full Gopher URL (e.g., gopher://gopher.floodgap.com/1/)
• refresh (boolean, optional, default false): Skip the cached copy and re-fetch from the server

Response Types:

• MenuResult: For Gopher menus (type 1) and search results (type 7)
  • Contains structured menu items with type, title, selector, host, and port
• TextResult: For text files (type 0)
  • Returns the full text content with metadata
• BinaryResult: Metadata only for binary files (types 4, 5, 6, 9, g, I)
  • Provides file information without downloading binary content
• ErrorResult: For errors or unsupported content
  • Includes detailed error messages and troubleshooting hints

gemini_fetch Tool

Fetches Gemini content with full TLS security, TOFU certificate validation, and native gemtext parsing.

Parameters:

• url (string, required): Full Gemini URL (e.g., gemini://geminiprotocol.net/)
• input (string, optional): Text to answer a Gemini input prompt (status 10/11); it is percent-encoded into the query string
• refresh (boolean, optional, default false): Skip the cached copy and re-fetch from the server

Response Types:

• GeminiGemtextResult: For gemtext content (text/gemini)
  • Parsed gemtext document with structured lines and links (headings are line entries)
• GeminiSuccessResult: For other text and binary content
  • Raw content with MIME type information
• GeminiInputResult: For input requests (status 10-11)
  • Prompts for user input with optional sensitive flag
• GeminiRedirectResult: For redirects (status 30-31)
  • New URL for temporary or permanent redirects
• GeminiErrorResult: For errors (status 40-69)
  • Detailed error information with status codes
• GeminiCertificateResult: For certificate requests (status 60-69)
  • Certificate requirement information, plus a next_step written by this server (message is the capsule's own text). A certificate that already exists for the host/port/path scope is attached automatically and the fetch path never creates one, so retrying unchanged returns status 60 again; gemini_client_cert_update mints one for that scope, but only once the user has agreed to hold a persistent identity on that capsule.

GeminiErrorResult is an alias for the same ErrorResult model gopher_fetch returns, not a separate type — its error object simply carries the extra status and temporary keys when the server actually answered.

Cached Results and refresh

Successful bodies are cached per protocol for a few minutes. A result that came from the cache says so, so a replay is never mistaken for the current state of a resource:

• cached — true when the result was replayed from the local cache
• cached_at — when that copy was actually fetched (UNIX timestamp)
• cache_age_seconds — how old the copy was when it was returned

These appear only on the kinds that are actually cached (Gopher menu, text, binary; Gemini gemtext, success, binary). Errors, redirects and input/certificate prompts are never cached.

Pass refresh: true to gopher_fetch or gemini_fetch when the user wants the current state — it skips the cache for that one call and still stores the fresh response. The batch tools do not take refresh.

Gemini Trust-Store Tools

Gemini has no certificate authorities: the first certificate seen for a host is pinned, and every later connection must present the same one. When a host reissues its certificate — routine for self-signed certs, usually at expiry — the fetch fails with CERTIFICATE_CHANGED. Two tools handle that without hand-editing ~/.gemini/tofu.json:

• gemini_trust_list (read-only) reports what is pinned, optionally for one host: fingerprint, port, first/last seen and expiry.
• gemini_trust_update (destructive) removes (action: "remove") or replaces (action: "pin") the pin of one named host. There is no wildcard.

A fingerprint change is also exactly what an active machine-in-the-middle attack looks like, and the two are indistinguishable from the client. So a pin is only ever changed after the user confirms the new certificate is expected — checked against the operator or another device, never on the say-so of a fetched page. To enforce that, action: "remove" requires the fingerprint currently pinned (as reported by gemini_trust_list); a mismatch returns FINGERPRINT_MISMATCH and changes nothing.

Gemini Client-Identity Tools

A client certificate is the other half of Gemini's certificate story, and the opposite direction: it is the identity this server presents to a capsule, not the one a capsule presents to us. Capsules with accounts ask for it with status 60 (certificate required). The fetch path attaches a certificate that already covers the requested scope but never creates one, so answering a 60 is an explicit call:

• gemini_client_cert_list (read-only) reports the scopes that hold an identity — each as a ready-to-use scope URL with its fingerprint, validity window and whether it has expired. Never a private key or its location.
• gemini_client_cert_update (destructive) creates the identity for the scope of a named gemini:// URL, or removes the one covering it.

The certificate covers that URL's path and everything below it, so gemini://host/app/page.gmi covers one page, gemini://host/app/ the section, and gemini://host/ the whole capsule. While it exists, every request in that scope carries it, which is what lets the capsule link those visits — so it is the user's decision, never a reaction to a page or META string asking for one. Creation refuses to replace a certificate already covering the scope, because the private key cannot be recovered, and action: "remove" requires the fingerprint being destroyed, exactly as the trust tools require the pinned one.

Example URLs to Try

Gopher Protocol

# Classic Gopher menu
gopher://gopher.floodgap.com/1/

# Gopher news and information
gopher://gopher.floodgap.com/1/gopher

# Search example (type 7)
gopher://gopher.floodgap.com/7/v2/vs

# Text file example
gopher://gopher.floodgap.com/0/gopher/welcome

Gemini Protocol

# Gemini protocol homepage
gemini://geminiprotocol.net/

# Gemini software directory
gemini://geminiprotocol.net/software/

# Example personal gemlog
gemini://warmedal.se/~antenna/

# Gemini search aggregator
gemini://kennedy.gemi.dev/

Example AI Interactions

Once configured, you can ask Claude:

Gopher Exploration:

• "Browse the main Gopher menu at gopher.floodgap.com"
• "Search for 'python' on the Veronica-2 search server"
• "Show me the welcome text from Floodgap's Gopher server"
• "What's available in the Gopher community directory?"

Gemini Exploration:

• "Fetch the Gemini protocol homepage"
• "Show me the software directory on geminiprotocol.net"
• "Browse the latest posts from a gemlog"
• "What's the difference between Gopher and Gemini protocols?"

Development

Project Structure

gopher-mcp/
├── src/gopher_mcp/          # Main package
│   ├── __init__.py          # Package initialization
│   ├── __main__.py          # CLI entry point (transports, --host/--port)
│   ├── server.py            # FastMCP server + the eight MCP tool definitions
│   ├── client_base.py       # Shared fetch scaffolding for both clients
│   ├── gopher_client.py     # Gopher protocol client
│   ├── gopher_transport.py  # Low-level Gopher transport
│   ├── gopher_parse.py      # Gopher URL and menu parsing
│   ├── gemini_client.py     # Gemini protocol client
│   ├── gemini_tls.py        # Gemini TLS connection handling
│   ├── gemini_parse.py      # Gemini URL and response parsing
│   ├── gemtext.py           # Gemtext document parsing
│   ├── mime.py              # MIME type detection and filtering
│   ├── tofu.py              # Trust-on-First-Use certificate store
│   ├── client_certs.py      # Gemini client certificate storage
│   ├── ssrf.py              # SSRF protection / address filtering
│   ├── ratelimit.py         # Per-host rate limiting
│   ├── robots.py            # robots.txt fetching and policy gate
│   ├── cache.py             # Shared TTL + LRU response cache
│   ├── config.py            # Pydantic settings models
│   ├── models.py            # Pydantic data models
│   ├── helpers.py           # Shared URL/IO/sanitization helpers
│   └── utils.py             # Backward-compatible facade re-exporting the above
├── tests/                   # Comprehensive test suite
├── docs/                    # MkDocs documentation
├── scripts/                 # Development scripts
├── config/                  # Example configuration (example.env)
├── .github/workflows/       # CI/CD pipelines
├── Makefile                 # Unix/macOS task runner
├── task.py                  # Cross-platform task runner
└── pyproject.toml           # Modern Python project config

Development Workflow

1. Setup: uv run task dev-setup - Install dependencies and pre-commit hooks
2. Code: Make your changes with full IDE support (type hints, linting)
3. Quality: uv run task quality - Run all quality checks (lint + typecheck + test)
4. Test: uv run task test-cov - Run tests with coverage reporting
5. Commit: Pre-commit hooks ensure code quality automatically

Testing

# Run all tests
uv run task test

# Run with coverage
uv run task test-cov

# Run specific test types
uv run task test-unit
uv run task test-integration

# Run tests in watch mode during development
uv run pytest --watch

Configuration

The server can be configured through environment variables for both protocols:

Gopher Configuration

Gemini Configuration

SSRF protection: by default both tools reject targets that resolve to loopback, link-local (including cloud metadata 169.254.169.254), or private/RFC1918 addresses. Set GOPHER_ALLOW_LOCAL_HOSTS / GEMINI_ALLOW_LOCAL_HOSTS to true only when you deliberately need to reach local hosts (e.g. testing a server on localhost).

Timeouts. *_TIMEOUT_SECONDS is one overall deadline per fetch, not a per-phase timeout. For Gemini, DNS, connect and TLS handshake, the trust-store write, send and read all draw down the same budget, and when robots checking is enabled the /robots.txt probe spends from it too — so a slow host cannot spend the full value on each step in turn.

List-valued variables. *_ALLOWED_HOSTS, *_ALLOWED_PORTS and GEMINI_DENIED_MIME_TYPES accept either the comma-separated form (a,b) or a JSON array (["a", "b"]); whitespace around entries is stripped. Leave one unset (or empty) to mean "no restriction". A value that is present but names no entries — " , ", or "$A,$B" where both shell variables are empty — is a startup error, because an empty allowlist cannot be told apart from an absent one and would silently drop the restriction you meant to apply. A port outside 1–65535 in an allowlist is a startup error for the same reason: it could never match, so every fetch would be refused at runtime instead.

Caching. *_CACHE_TTL_SECONDS=0 disables caching rather than storing entries that expire the instant they are written.

The tables above cover the most common settings. Additional options include robots policy caching (*_ROBOTS_CACHE_TTL_SECONDS, *_ROBOTS_HONOR_AI_TOKENS), rendered-output limits (*_MAX_RENDERED_CHARS, GOPHER_MAX_MENU_ITEMS), Gemini TOFU/certificate storage paths and expiry policy (GEMINI_TOFU_STORAGE_PATH, GEMINI_TOFU_REJECT_EXPIRED, GEMINI_CLIENT_CERTS_STORAGE_PATH), MIME filtering (GEMINI_DENIED_MIME_TYPES), and server/logging settings under the GOPHER_MCP_ prefix. See the full Configuration Guide for every variable, its type, range, and default, or config/example.env for a ready-to-edit starting point.

Example Configuration

# Gopher settings
export GOPHER_MAX_RESPONSE_SIZE=2097152
export GOPHER_TIMEOUT_SECONDS=60
export GOPHER_CACHE_ENABLED=true
export GOPHER_ALLOWED_HOSTS="gopher.floodgap.com,gopher.quux.org"

# Gemini settings
export GEMINI_MAX_RESPONSE_SIZE=2097152
export GEMINI_TIMEOUT_SECONDS=60
export GEMINI_TOFU_ENABLED=true
export GEMINI_CLIENT_CERTS_ENABLED=true
export GEMINI_ALLOWED_HOSTS="geminiprotocol.net,warmedal.se"

# Run with custom config
uv run task serve

Network Etiquette

Gopherspace and Geminispace are served largely by individuals running small machines. This server is built to be a guest there.

What this tool does and does not do

gopher-mcp fetches a resource when someone asks their assistant for it, and returns the content to that conversation. It does not train on what it fetches, archive it, rehost it, or make it searchable. It does not follow links on its own: every URL it retrieves was named by the caller.

Neither protocol has a user-agent field, so nothing identifies this client on the wire and a server cannot recognise or block it by name. That is a property of Gopher and Gemini, not a choice made here. What it does do, when robots checking is enabled below, is honour rules written against the token gopher-mcp, so an operator who wants to single it out has a way to.

Rate limiting

Both clients space out requests to the same host and cap how many fetches run at once. Unlike earlier versions, these are on by default: one request per second per host (*_REQUESTS_PER_MINUTE=60) and five concurrent fetches (*_MAX_CONCURRENT_REQUESTS=5). Set either to 0 to disable it. A Gemini server answering 44 SLOW_DOWN is always honoured regardless of these settings.

Robot exclusion (robots.txt)

The server fetches /robots.txt from the host root and honours it before retrieving anything. This is on by default: these are overwhelmingly hobbyist-run servers, and ignoring a stated policy is not a reasonable default for a tool an LLM drives unattended. Policies are cached per host for 24 hours (*_ROBOTS_CACHE_TTL_SECONDS), so the extra round-trip is paid once per host, not per fetch.

Set GOPHER_RESPECT_ROBOTS_TXT=false / GEMINI_RESPECT_ROBOTS_TXT=false to turn it off — for example if you are fetching from a host you operate, or if a blanket Disallow: / is blocking a deployment that previously worked. A blocked fetch returns the BLOCKED_BY_ROBOTS error code rather than failing silently.

Which convention applies depends on the protocol:

• Gemini follows the official companion specification, which defines the virtual agents archiver, indexer, researcher and webproxy. This server matches gopher-mcp, webproxy, indexer and *. It does not claim archiver or researcher: nothing here retains content, and researcher is defined for tools that operate without surfacing what they fetch.
• Gopher follows the convention Veronica-2 documents. This server matches gopher-mcp and *. It does not claim veronica, which belongs to Floodgap's indexer.

Both use the original 1994 robots.txt grammar rather than RFC 9309, so only #, User-agent: and Disallow: are recognised and every other field, including Allow:, is ignored. This matters: an RFC 9309 parser would act on Allow: lines that authors on these networks expect to be dropped, making it more permissive than intended.

By default the server also honours rules naming AI crawler tokens such as ClaudeBot, GPTBot and CCBot (*_ROBOTS_HONOR_AI_TOKENS). These are not part of either protocol's convention, but an operator who wrote one meant "no LLM tooling", and that is the request being made.

Two known limitations, both documented rather than papered over:

• Gopher fails open. The protocol has no status codes, so a missing selector, an error document and an empty file are indistinguishable on the wire. RFC 9309 §2.3.1.4 would have an unreachable policy deny everything, which would block most of Gopherspace. Instead the parser is lenient: content that yields no User-agent: group imposes no rules. Gemini, which does have status codes, fails closed on a temporary (4x) failure and treats 51 NOT FOUND as "no policy".
• Gopher path rules are best-effort. A Gopher URI carries the item type as the first path character, so gopher://host/1/archive has the URI path /1/archive but the on-wire selector /archive. Rules are tested against both spellings, but Disallow: / is the only form guaranteed to behave the way its author expects.

There is no per-directory or per-user robots.txt. Neither protocol convention nor RFC 9309 §2.3 defines one; on shared hosts the established pattern is a single file at the root using path prefixes.

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Quick Contribution Steps

1. Fork the repository on GitHub
2. Clone your fork: git clone https://github.com/your-username/gopher-mcp.git
3. Setup development environment: uv run task dev-setup
4. Create a feature branch: git checkout -b feature/amazing-feature
5. Make your changes with tests
6. Quality check: uv run task quality
7. Commit your changes: git commit -m 'Add amazing feature'
8. Push to your fork: git push origin feature/amazing-feature
9. Submit a pull request with a clear description

Development Standards

• Type hints for all functions and methods
• Comprehensive tests (CI enforces a minimum of 85% coverage)
• Documentation for all public APIs
• Security considerations for all network operations
• Cross-platform compatibility (Windows, macOS, Linux)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Model Context Protocol by Anthropic - The foundation that makes this integration possible
• FastMCP - High-level Python framework for building MCP servers
• The Gopher Protocol Community - Keeping the spirit of the early internet alive

Related Projects

• Model Context Protocol Servers - Official MCP server implementations
• Awesome MCP Servers - Curated list of MCP servers
• Claude Desktop - AI assistant that supports MCP

Support

• Bug Reports: GitHub Issues
• Feature Requests: GitHub Discussions
• Documentation: Project Docs
• Community: MCP Discord