A modern cross-platform MCP server that enables AI assistants to safely and efficiently browse and interact with resources from the Gopher and Gemini protocols.

Installation

Development Installation

git clone https://github.com/cameronrye/gopher-mcp.git
cd gopher-mcp
./scripts/dev-setup.sh  # Unix/macOS
# or
scripts\dev-setup.bat   # Windows
uv run task serve

Installation via PyPI

pip install gopher-mcp
# Or with uv
uv add gopher-mcp

Installation from GitHub

uv add git+https://github.com/cameronrye/gopher-mcp.git
# Or development mode installation
git clone https://github.com/cameronrye/gopher-mcp.git
cd gopher-mcp
uv sync --all-extras

Configuration

Claude Desktop (Unix/macOS/Linux)

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

Claude Desktop (Windows)

{
  "mcpServers": {
    "gopher": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\gopher-mcp",
        "run",
        "task",
        "serve"
      ],
      "env": {
        "MAX_RESPONSE_SIZE": "1048576",
        "TIMEOUT_SECONDS": "30"
      }
    }
  }
}

Available Tools

Tool	Description
gopher_fetch	Fetches Gopher menus, text files, or metadata from URLs with comprehensive error handling and security...
gemini_fetch	Fetches Gemini content with full TLS security, TOFU certificate validation, and native gemtext parsing...

Features

• Support for two protocols: gopher_fetch and gemini_fetch tools for comprehensive protocol coverage
• Full Gopher support: Handles menus (type 1), text files (type 0), search servers (type 7), and binary files
• Complete Gemini implementation: Native gemtext parsing, TLS security, and status code handling
• Advanced security: TOFU certificate validation, client certificates, and secure TLS connections
• Security 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
• High performance: Async/await patterns with intelligent caching

Environment Variables

Optional

• GOPHER_MAX_RESPONSE_SIZE - Maximum response size in bytes
• GOPHER_TIMEOUT_SECONDS - Request timeout in seconds
• GOPHER_CACHE_ENABLED - Enable response caching
• GOPHER_CACHE_TTL_SECONDS - Cache time-to-live in seconds
• GOPHER_ALLOWED_HOSTS - Comma-separated list of allowed hosts
• GEMINI_MAX_RESPONSE_SIZE - Maximum response size in bytes
• GEMINI_TIMEOUT_SECONDS - Request timeout in seconds
• GEMINI_CACHE_ENABLED - Enable response caching

Usage Examples

View the main Gopher menu on gopher.floodgap.com

Search for 'python' on the Veronica-2 search server

Show the welcome text from the Floodgap Gopher server

What's available in the Gopher community directory?

Get the Gemini protocol home page

Notes

Requires Python 3.11+ and the uv package manager. Includes comprehensive documentation, full test coverage, and modern development practices with async/await patterns.