gopher-mcp

# Gopher & Gemini MCP Server

<!-- mcp-name: io.github.cameronrye/gopher-mcp -->

[![CI](https://github.com/cameronrye/gopher-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/cameronrye/gopher-mcp/actions/workflows/ci.yml)
[![Documentation](https://github.com/cameronrye/gopher-mcp/actions/workflows/docs.yml/badge.svg)](https://github.com/cameronrye/gopher-mcp/actions/workflows/docs.yml)
[![PyPI version](https://badge.fury.io/py/gopher-mcp.svg)](https://badge.fury.io/py/gopher-mcp)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
[![Downloads](https://pepy.tech/badge/gopher-mcp)](https://pepy.tech/project/gopher-mcp)

A modern, cross-platform [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants to
browse and interact with both [Gopher protocol](<https://en.wikipedia.org/wiki/Gopher_(protocol)>) and
[Gemini protocol](https://geminiprotocol.net/) 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](https://cameronrye.github.io/gopher-mcp)**

- [Installation Guide](https://cameronrye.github.io/gopher-mcp/installation/)
- [Configuration Guide](https://cameronrye.github.io/gopher-mcp/configuration/)
- [API Reference](https://cameronrye.github.io/gopher-mcp/api-reference/)
- [AI Assistant Guide](https://cameronrye.github.io/gopher-mcp/ai-assistant-guide/)
- [Migration Guide](https://cameronrye.github.io/gopher-mcp/migration-guide/) and
  [Changelog](https://cameronrye.github.io/gopher-mcp/changelog/) — what changed,
  and what an upgrade asks of you

## Quick Start

### Prerequisites

- **Python 3.11+** - [Download here](https://www.python.org/downloads/)
- **uv package manager** - [Install uv](https://docs.astral.sh/uv/getting-started/installation/)

### Installation

#### Option 1: Zero-install with uvx (Recommended)

No clone, no checkout — [uv](https://docs.astral.sh/uv/) fetches and runs the
published package on demand:

```bash
uvx gopher-mcp
```

#### Option 2: PyPI Installation

```bash
# Install from PyPI
pip install gopher-mcp

# Or with uv
uv add gopher-mcp
```

#### Option 3: Development Installation

```bash
# 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:

```bash
# 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:

| Client         | Where the entry goes                                                                                                                                                                      | Top-level key     |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| Claude