Gopher

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, client certificates, and secure TLS connections
• Safety First: Built-in timeouts, size limits, input sanitization, 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

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

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"
      }
    }
  }
}

On Windows use the absolute path with escaped backslashes (C:\\path\\to\\gopher-mcp).

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 provides four MCP tools for exploring alternative internet protocols: gopher_fetch and gemini_fetch for single resources, plus gopher_batch_fetch and gemini_batch_fetch for fetching several URLs at once (bounded concurrency, capped list length).

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/)

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

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

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 + MCP tool definitions
│   ├── gopher_client.py     # Gopher protocol client
│   ├── gopher_transport.py  # Low-level Gopher transport
│   ├── gemini_client.py     # Gemini protocol client
│   ├── gemini_tls.py        # Gemini TLS connection handling
│   ├── tofu.py              # Trust-on-First-Use certificate store
│   ├── client_certs.py      # Gemini client certificate management
│   ├── ssrf.py              # SSRF protection / address filtering
│   ├── ratelimit.py         # Per-host rate limiting
│   ├── cache.py             # Per-protocol response cache
│   ├── config.py            # Pydantic settings models
│   ├── models.py            # Pydantic data models
│   └── utils.py             # Utility functions
├── 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 --wat

…