AllTrails Client

A Model Context Protocol (MCP) server and Python package for searching hiking trails from AllTrails.com. Includes smart caching to avoid rate limiting.

⚠️ Important: Rate Limiting

AllTrails.com implements CAPTCHA and rate limiting. This package includes a caching system to minimize requests:

• ✅ Cache-first: Stores up to 15 trails per park for 7 days
• 🔄 Automatic refresh: Updates cache after expiration
• 💾 SQLite storage: Local database (trails_cache.db)
• 🚫 Use sparingly: Best for personal, low-volume usage

Features

• 🥾 Search trails by US National Park (all 63 parks supported)
• 📍 Get detailed trail information
• 💾 Smart caching system (7-day cache)
• 🤖 MCP server for Claude Desktop integration
• 🛠️ CLI tools for quick searches
• 🐍 Python API for programmatic access

Installation

From PyPI (when published)

pip install alltrails-mcp

Development Install

git clone https://github.com/dbrown540/alltrails-mcp-client.git
cd alltrails-mcp-client
pip install -e .

Quick Start

Python API

from alltrails_mcp import NationalPark, search_trails_with_cache

# Search with automatic caching
trails = search_trails_with_cache(NationalPark.YOSEMITE.value)

for trail in trails[:5]:
    print(f"{trail['name']} - {trail['difficulty']} - {trail['length']}")

CLI

# Search trails
alltrails-search search us/california/yosemite-national-park --limit 5

# Get trail details
alltrails-search details us/california/half-dome-trail

# Show cache info and location
alltrails-search cache

# Clear the cache
alltrails-search cache --clear

# View current configuration
alltrails-search config

# Set cache expiration to 14 days
alltrails-search config --set-cache-days 14

MCP Server (Claude Desktop)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "alltrails": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/alltrails-mcp-client/src/alltrails_mcp/server.py"],
      "env": {
        "ALLTRAILS_CACHE_DAYS": "14"
      }
    }
  }
}

Optional environment variables:

• ALLTRAILS_CACHE_DAYS: Cache expiration in days (default: 7)

Then ask Claude: "Find trails in Yosemite National Park"

National Parks

All 63 US National Parks are available via the NationalPark enum:

from alltrails_mcp import NationalPark, get_park_slug, list_parks

# Use enum
park = NationalPark.YOSEMITE
slug = park.value  # 'us/california/yosemite-national-park'

# Look up by name
slug = get_park_slug("Yellowstone")

# List all parks
all_parks = list_parks()

See PARKS_SUMMARY.md for complete list.

Cache Management

from alltrails_mcp import TrailCache

cache = TrailCache()

# Get cache info
info = cache.get_cache_info()
print(f"Parks cached: {info['total_parks']}")

# Clear specific park
cache.clear_cache("us/california/yosemite-national-park")

# Clear entire cache
cache.clear_cache()

# Force refresh (bypass cache)
from alltrails_mcp import search_trails_with_cache
trails = search_trails_with_cache(park_slug, force_refresh=True)

# Use custom cache location
from pathlib import Path
custom_cache = TrailCache(db_path=Path("/custom/path/cache.db"))

# Use custom cache expiration (e.g., 14 days)
custom_cache = TrailCache(cache_days=14)

Cache Location:

• Linux/macOS: ~/.cache/alltrails-mcp/trails_cache.db
• Fallback: ~/.alltrails_mcp/trails_cache.db
• Custom: Pass db_path to TrailCache()

Cache Expiration Configuration:

Cache expiration can be configured in multiple ways with the following priority:

1. Programmatic (highest priority): Pass cache_days=14 to TrailCache()
2. Environment variable: Set ALLTRAILS_CACHE_DAYS=14
3. Saved configuration: Use CLI command alltrails-search config --set-cache-days 14
4. Default: 7 days

# Set cache expiration persistently via CLI
alltrails-search config --set-cache-days 14

# View current configuration
alltrails-search config

# Override via environment variable
export ALLTRAILS_CACHE_DAYS=30

Configuration is saved to ~/.cache/alltrails-mcp/config.json and persists across sessions.

The cache is automatically managed - users don't need to interact with it directly unless they want to clear it or customize the location/expiration.

Examples

See the examples/ directory:

• demo.py - Simple demonstration of key features

Run with:

python examples/demo.py --park ZION
python examples/demo.py --stats
python examples/demo.py --clear-cache

Project Structure

alltrails-mcp-client/
├── src/alltrails_mcp/      # Main package
│   ├── __init__.py          # Package exports
│   ├── scraper.py           # AllTrails scraping logic
│   ├── cache.py             # SQLite caching system
│   ├── parks.py             # National Park enums
│   ├── server.py            # MCP server
│   └── cli.py               # Command-line interface
├── examples/                # Example scripts
├── pyproject.toml          # Package configuration
└── README.md               # This file

API Reference

Core Functions

search_trails_in_park(park_slug: str) -> List[Dict]

• Search for trails (no caching)
• Returns: List of trail dictionaries

search_trails_with_cache(park_slug: str, cache=None, force_refresh=False, limit=15) -> List[Dict]

• Search with automatic caching
• Returns cached data if valid (<7 days old)

get_trail_by_slug(slug: str) -> Dict

• Get detailed trail information
• Example slug: us/tennessee/alum-cave-trail

Trail Dictionary Format

{
    "name": "Half Dome Trail",
    "url": "https://www.alltrails.com/trail/...",
    "summary": "Experience this 14.2-mile...",
    "difficulty": "Hard",
    "length": "14.2 mi",
    "rating": "4.8"
}

Publishing to PyPI

See PUBLISHING.md for detailed instructions.

Quick steps:

# Build
python -m build

# Upload
twine upload dist/*

License

MIT License - See LICENSE.md

Acknowledgments

• Original MCP server by Srinath Srinivasan
• Forked and enhanced by Danny Brown
• Trail data from AllTrails
• Built with Model Context Protocol

Disclaimer

This tool scrapes publicly available data from AllTrails. Use responsibly and respect AllTrails' terms of service. The caching system helps minimize requests.