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. 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 Gophersp
Add this skill
npx mdskills install cameronrye/gopher-mcpWell-documented MCP server enabling AI access to Gopher and Gemini protocols with robust security features
1# Gopher & Gemini MCP Server23[](https://github.com/cameronrye/gopher-mcp/actions/workflows/ci.yml)4[](https://github.com/cameronrye/gopher-mcp/actions/workflows/docs.yml)5[](https://badge.fury.io/py/gopher-mcp)6[](https://www.python.org/downloads/)7[](https://opensource.org/licenses/MIT)8[](https://codecov.io/gh/cameronrye/gopher-mcp)9[](https://github.com/astral-sh/ruff)10[](https://mypy-lang.org/)11[](https://pepy.tech/project/gopher-mcp)1213A modern, cross-platform [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants to14browse and interact with both [Gopher protocol](<https://en.wikipedia.org/wiki/Gopher_(protocol)>) and15[Gemini protocol](https://geminiprotocol.net/) resources safely and efficiently.1617## Overview1819The Gopher & Gemini MCP Server bridges vintage and modern alternative internet protocols with AI assistants, allowing LLMs like20Claude to explore the unique content and communities that thrive on both Gopherspace and Geminispace. Built with FastMCP and21modern Python practices, it provides secure, efficient gateways to these distinctive internet protocols.2223**Key Benefits:**2425- **Discover alternative internet content** - Access unique resources on both Gopher and Gemini protocols26- **Safe exploration** - Built-in security safeguards, TLS encryption, and content filtering27- **Modern implementation** - Uses FastMCP framework with async/await patterns28- **Developer-friendly** - Comprehensive testing, type hints, and documentation29- **Advanced security** - TOFU certificate validation and client certificate support for Gemini3031## Features3233- **Dual Protocol Support**: `gopher_fetch` and `gemini_fetch` tools for comprehensive protocol coverage34- **Comprehensive Gopher Support**: Handles menus (type 1), text files (type 0), search servers (type 7), and binary files35- **Full Gemini Implementation**: Native gemtext parsing, TLS security, and status code handling36- **Advanced Security**: TOFU certificate validation, client certificates, and secure TLS connections37- **Safety First**: Built-in timeouts, size limits, input sanitization, and host allowlists38- **LLM-Optimized**: Returns structured JSON responses designed for AI consumption39- **Cross-Platform**: Works seamlessly on Windows, macOS, and Linux40- **Modern Development**: Full type checking, linting, testing, and CI/CD pipeline41- **High Performance**: Async/await patterns with intelligent caching4243## Documentation4445Complete documentation is available at **[cameronrye.github.io/gopher-mcp](https://cameronrye.github.io/gopher-mcp)**4647- [Installation Guide](https://cameronrye.github.io/gopher-mcp/installation/)48- [API Reference](https://cameronrye.github.io/gopher-mcp/api-reference/)49- [Advanced Features](https://cameronrye.github.io/gopher-mcp/advanced-features/)50- [AI Assistant Guide](https://cameronrye.github.io/gopher-mcp/ai-assistant-guide/)5152## Quick Start5354### Prerequisites5556- **Python 3.11+** - [Download here](https://www.python.org/downloads/)57- **uv package manager** - [Install uv](https://docs.astral.sh/uv/getting-started/installation/)5859### Installation6061#### Option 1: Development Installation (Recommended)6263```bash64# Clone the repository65git clone https://github.com/cameronrye/gopher-mcp.git66cd gopher-mcp6768# Set up development environment69./scripts/dev-setup.sh # Unix/macOS70# or71scripts\dev-setup.bat # Windows7273# Run the server74uv run task serve75```7677#### Option 2: PyPI Installation7879```bash80# Install from PyPI (recommended for end users)81pip install gopher-mcp8283# Or with uv84uv add gopher-mcp85```8687#### Option 3: Development Installation8889```bash90# Install directly from GitHub91uv add git+https://github.com/cameronrye/gopher-mcp.git9293# Or install in development mode94git clone https://github.com/cameronrye/gopher-mcp.git95cd gopher-mcp96uv sync --all-extras97```9899### Claude Desktop Integration100101Add to your `claude_desktop_config.json`:102103**Unix/macOS/Linux:**104105```json106{107 "mcpServers": {108 "gopher": {109 "command": "uv",110 "args": ["--directory", "/path/to/gopher-mcp", "run", "task", "serve"],111 "env": {112 "MAX_RESPONSE_SIZE": "1048576",113 "TIMEOUT_SECONDS": "30"114 }115 }116 }117}118```119120**Windows:**121122```json123{124 "mcpServers": {125 "gopher": {126 "command": "uv",127 "args": [128 "--directory",129 "C:\\path\\to\\gopher-mcp",130 "run",131 "task",132 "serve"133 ],134 "env": {135 "MAX_RESPONSE_SIZE": "1048576",136 "TIMEOUT_SECONDS": "30"137 }138 }139 }140}141```142143## Cross-Platform Development144145This project includes a **unified Python-based task management system** that works across all platforms:146147### Recommended (All Platforms)148149```bash150python task.py <command> # Unified Python task runner (recommended)151```152153### Alternative Options154155```bash156# Unix/macOS/Linux157make <command> # Traditional make (delegates to task.py)158159# Universal fallback160uv run task <command> # Direct taskipy usage161```162163### Available Commands164165| Command | Description |166| ------------------ | ------------------------------ |167| `dev-setup` | Set up development environment |168| `install-hooks` | Install pre-commit hooks |169| `lint` | Run ruff linting |170| `format` | Format code with ruff |171| `typecheck` | Run mypy type checking |172| `quality` | Run all quality checks |173| `check` | Run lint + typecheck |174| `test` | Run all tests |175| `test-cov` | Run tests with coverage |176| `test-unit` | Run unit tests only |177| `test-integration` | Run integration tests |178| `serve` | Run MCP server (stdio) |179| `serve-http` | Run MCP server (HTTP) |180| `docs-serve` | Serve docs locally |181| `docs-build` | Build documentation |182| `clean` | Clean build artifacts |183| `ci` | Run CI pipeline locally |184185## Usage186187The server provides two powerful MCP tools for exploring alternative internet protocols:188189### `gopher_fetch` Tool190191Fetches Gopher menus, text files, or metadata by URL with comprehensive error handling and security safeguards.192193**Parameters:**194195- `url` (string, required): Full Gopher URL (e.g., `gopher://gopher.floodgap.com/1/`)196197**Response Types:**198199- **MenuResult**: For Gopher menus (type 1) and search results (type 7)200 - Contains structured menu items with type, display text, selector, host, and port201- **TextResult**: For text files (type 0)202 - Returns the full text content with metadata203- **BinaryResult**: Metadata only for binary files (types 4, 5, 6, 9, g, I)204 - Provides file information without downloading binary content205- **ErrorResult**: For errors or unsupported content206 - Includes detailed error messages and troubleshooting hints207208### `gemini_fetch` Tool209210Fetches Gemini content with full TLS security, TOFU certificate validation, and native gemtext parsing.211212**Parameters:**213214- `url` (string, required): Full Gemini URL (e.g., `gemini://geminiprotocol.net/`)215216**Response Types:**217218- **GeminiGemtextResult**: For gemtext content (text/gemini)219 - Parsed gemtext document with structured lines, links, and headings220- **GeminiSuccessResult**: For other text and binary content221 - Raw content with MIME type information222- **GeminiInputResult**: For input requests (status 10-11)223 - Prompts for user input with optional sensitive flag224- **GeminiRedirectResult**: For redirects (status 30-31)225 - New URL for temporary or permanent redirects226- **GeminiErrorResult**: For errors (status 40-69)227 - Detailed error information with status codes228- **GeminiCertificateResult**: For certificate requests (status 60-69)229 - Certificate requirement information230231### Example URLs to Try232233#### Gopher Protocol234235```bash236# Classic Gopher menu237gopher://gopher.floodgap.com/1/238239# Gopher news and information240gopher://gopher.floodgap.com/1/gopher241242# Search example (type 7)243gopher://gopher.floodgap.com/7/v2/vs244245# Text file example246gopher://gopher.floodgap.com/0/gopher/welcome247```248249#### Gemini Protocol250251```bash252# Gemini protocol homepage253gemini://geminiprotocol.net/254255# Gemini software directory256gemini://geminiprotocol.net/software/257258# Example personal gemlog259gemini://warmedal.se/~antenna/260261# Gemini search aggregator262gemini://kennedy.gemi.dev/263```264265### Example AI Interactions266267Once configured, you can ask Claude:268269**Gopher Exploration:**270271- _"Browse the main Gopher menu at gopher.floodgap.com"_272- _"Search for 'python' on the Veronica-2 search server"_273- _"Show me the welcome text from Floodgap's Gopher server"_274- _"What's available in the Gopher community directory?"_275276**Gemini Exploration:**277278- _"Fetch the Gemini protocol homepage"_279- _"Show me the software directory on geminiprotocol.net"_280- _"Browse the latest posts from a gemlog"_281- _"What's the difference between Gopher and Gemini protocols?"_282283## Development284285### Project Structure286287```text288gopher-mcp/289├── src/gopher_mcp/ # Main package290│ ├── __init__.py # Package initialization291│ ├── server.py # FastMCP server implementation292│ ├── gopher_client.py # Gopher protocol client293│ ├── models.py # Pydantic data models294│ ├── tools.py # MCP tool definitions295│ └── utils.py # Utility functions296├── tests/ # Comprehensive test suite297│ ├── test_server.py # Server tests298│ ├── test_gopher_client.py # Client tests299│ └── test_integration.py # Integration tests300├── docs/ # MkDocs documentation301├── scripts/ # Development scripts302├── .github/workflows/ # CI/CD pipelines303├── Makefile # Unix/macOS task runner304├── task.bat # Windows task runner305└── pyproject.toml # Modern Python project config306```307308### Development Workflow3093101. **Setup**: `uv run task dev-setup` - Install dependencies and pre-commit hooks3112. **Code**: Make your changes with full IDE support (type hints, linting)3123. **Quality**: `uv run task quality` - Run all quality checks (lint + typecheck + test)3134. **Test**: `uv run task test-cov` - Run tests with coverage reporting3145. **Commit**: Pre-commit hooks ensure code quality automatically315316### Testing317318```bash319# Run all tests320uv run task test321322# Run with coverage323uv run task test-cov324325# Run specific test types326uv run task test-unit327uv run task test-integration328329# Run tests in watch mode during development330uv run pytest --watch331```332333## Configuration334335The server can be configured through environment variables for both protocols:336337### Gopher Configuration338339| Variable | Description | Default | Example |340| -------------------------- | ------------------------------ | --------------- | ---------------------- |341| `GOPHER_MAX_RESPONSE_SIZE` | Maximum response size in bytes | `1048576` (1MB) | `2097152` |342| `GOPHER_TIMEOUT_SECONDS` | Request timeout in seconds | `30` | `60` |343| `GOPHER_CACHE_ENABLED` | Enable response caching | `true` | `false` |344| `GOPHER_CACHE_TTL_SECONDS` | Cache time-to-live in seconds | `300` | `600` |345| `GOPHER_ALLOWED_HOSTS` | Comma-separated allowed hosts | `None` (all) | `example.com,test.com` |346347### Gemini Configuration348349| Variable | Description | Default | Example |350| ----------------------------- | ---------------------------------- | --------------- | ---------------------- |351| `GEMINI_MAX_RESPONSE_SIZE` | Maximum response size in bytes | `1048576` (1MB) | `2097152` |352| `GEMINI_TIMEOUT_SECONDS` | Request timeout in seconds | `30` | `60` |353| `GEMINI_CACHE_ENABLED` | Enable response caching | `true` | `false` |354| `GEMINI_CACHE_TTL_SECONDS` | Cache time-to-live in seconds | `300` | `600` |355| `GEMINI_ALLOWED_HOSTS` | Comma-separated allowed hosts | `None` (all) | `example.org,test.org` |356| `GEMINI_TOFU_ENABLED` | Enable TOFU certificate validation | `true` | `false` |357| `GEMINI_CLIENT_CERTS_ENABLED` | Enable client certificate support | `true` | `false` |358359### Example Configuration360361```bash362# Gopher settings363export GOPHER_MAX_RESPONSE_SIZE=2097152364export GOPHER_TIMEOUT_SECONDS=60365export GOPHER_CACHE_ENABLED=true366export GOPHER_ALLOWED_HOSTS="gopher.floodgap.com,gopher.quux.org"367368# Gemini settings369export GEMINI_MAX_RESPONSE_SIZE=2097152370export GEMINI_TIMEOUT_SECONDS=60371export GEMINI_TOFU_ENABLED=true372export GEMINI_CLIENT_CERTS_ENABLED=true373export GEMINI_ALLOWED_HOSTS="geminiprotocol.net,warmedal.se"374375# Run with custom config376uv run task serve377```378379## Contributing380381We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.382383### Quick Contribution Steps3843851. **Fork** the repository on GitHub3862. **Clone** your fork: `git clone https://github.com/your-username/gopher-mcp.git`3873. **Setup** development environment: `uv run task dev-setup`3884. **Create** a feature branch: `git checkout -b feature/amazing-feature`3895. **Make** your changes with tests3906. **Quality** check: `uv run task quality`3917. **Commit** your changes: `git commit -m 'Add amazing feature'`3928. **Push** to your fork: `git push origin feature/amazing-feature`3939. **Submit** a pull request with a clear description394395### Development Standards396397- **Type hints** for all functions and methods398- **Comprehensive tests** with >90% coverage399- **Documentation** for all public APIs400- **Security** considerations for all network operations401- **Cross-platform** compatibility (Windows, macOS, Linux)402403## License404405This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.406407## Acknowledgments408409- **[Model Context Protocol](https://modelcontextprotocol.io/)** by Anthropic - The foundation that makes this integration possible410- **[FastMCP](https://github.com/jlowin/fastmcp)** - High-level Python framework for building MCP servers411- **[Pituophis](https://github.com/dotcomboom/pituophis)** - Excellent Python Gopher client library412- **The Gopher Protocol Community** - Keeping the spirit of the early internet alive413414## Related Projects415416- [Model Context Protocol Servers](https://github.com/modelcontextprotocol/servers) - Official MCP server implementations417- [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers) - Curated list of MCP servers418- [Claude Desktop](https://claude.ai/download) - AI assistant that supports MCP419420## Support421422- **Bug Reports**: [GitHub Issues](https://github.com/cameronrye/gopher-mcp/issues)423- **Feature Requests**: [GitHub Discussions](https://github.com/cameronrye/gopher-mcp/discussions)424- **Documentation**: [Project Docs](https://cameronrye.github.io/gopher-mcp/)425- **Community**: [MCP Discord](https://discord.gg/modelcontextprotocol)426427---428429<div align="center">430431Made with ❤️ by [Cameron Rye](https://rye.dev/)432433[Star this project](https://github.com/cameronrye/gopher-mcp) if you find it useful!434435</div>436
Full transparency — inspect the skill content before installing.