Content
# surf brain ™
> **Disclaimer:** This is a hobby project for personal use only. It is intended for users who already subscribe to [Surfline](https://www.surfline.com/) and is meant to augment the experience of using the platform — not to replace or profit from it in any way. If anyone at Surfline would like to discuss this project, I'm happy to chat — reach me at [kowalsska.dev@gmail.com](mailto:kowalsska.dev@gmail.com). This is a passion project built by a surfer who uses Surfline every day.
Your personal surf intelligence assistant. Talk to Claude about the surf and get real conditions, forecasts, and recommendations for surf spots worldwide — powered by Surfline data.
<p align="center">
<strong>"When should I surf this week?"</strong> → finds the best windows across your local spots<br>
<strong>"Strike mission in Portugal next week?"</strong> → scans every spot in the region for what's firing<br>
<strong>"Carcavelos should only be surfed at low tide"</strong> → saves your local knowledge per spot<br>
<strong>"I surfed Supertubos this morning, head-high and fun, 8/10"</strong> → logged with matched forecast
</p>
---
## Setup
### 1. Install
If you don't have Python 3.12+ and [uv](https://docs.astral.sh/uv/) yet:
```bash
# macOS
brew install python@3.12
curl -LsSf https://astral.sh/uv/install.sh | sh
# Linux
sudo apt install python3.12 # or your distro's equivalent
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
winget install Python.Python.3.12
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
Then clone and install dependencies:
```bash
git clone https://github.com/magdawg/surf-brain-mcp.git
cd surf-brain-mcp
uv sync
```
### 2. Connect to Claude
**Claude Code:**
```bash
claude mcp add surf-brain -- uv run python main.py
```
**Claude Desktop** — add to `claude_desktop_config.json` (make sure `cwd` points to where you cloned surf-brain on your machine):
```json
{
"mcpServers": {
"surfline": {
"command": "uv",
"args": ["run", "python", "main.py"],
"cwd": "/path/to/surf_brain_mcp"
}
}
}
```
### Optional: Surfline credentials
If you have a Surfline account, create a `.env` file in the surf-brain directory with your login:
```bash
# from the surf-brain directory
echo 'SURFLINE_EMAIL=your@email.com' >> .env
echo 'SURFLINE_PASSWORD=yourpassword' >> .env
```
surf-brain works without credentials, but full functionality requires a [Surfline Premium](https://www.surfline.com/create-account) subscription.
### 3. Set your home location
On first use, tell surf-brain where you surf:
> "I surf in Peniche, Portugal"
It discovers nearby spots automatically and sets up your home region. All daily tools — "how's the surf?", "best spot right now?", "when should I surf this week?" — use your home region. You can add more anytime:
> "I also surf in Biarritz" → added as a home region (included in daily checks)
> "Add Bali to my favorites" → added as a favorite (for trip planning, not daily checks)
---
## What's under the hood
### 9,000+ spots worldwide
surf-brain works with every spot on Surfline across 139 countries. Set your home region and it discovers nearby spots instantly. Search by name, browse by country, or find spots near any coordinates.
### Knows what works at each spot
For premium spots, surf-brain knows the ideal conditions — best swell, wind, tide, size range, season, and break type. Ask "what works best at Pipeline?" and you get the answer instantly. You can override any of it with your own preferences and local knowledge. This data stays private to you.
### Learns from your sessions
Log your sessions and surf-brain starts scoring spots based on what you personally enjoy — not just generic conditions. It matches the forecast for when you were actually in the water, and over time it learns which conditions you rate highest.
### Strike missions
Explore beyond your usual spots. Give it a region and surf-brain scans every spot in the area, previews the count, and — once you confirm — fetches live forecasts in parallel. Off-the-radar spots surface first.
> "Strike mission in northern Spain?"
### Your data stays on your machine
All personal data — your regions, spot preferences, and session history — is stored locally in a SQLite database on your machine. Nothing is sent to any external server. surf-brain only talks to the Surfline API to fetch forecasts.
---
## What you can do
### Check the surf
> "How's the surf?"
Get conditions for all your local spots — wave height, swell period, wind, Surfline rating, plus surf-brain's own 0-10 score and plain-english tags like "light offshore — glassy" or "blown out". Includes an 8-hour forecast so you can time your session.
> "How's the wind?"
Live sensor readings (where available) alongside forecast data, with transition alerts so you know when the wind is about to turn onshore.
> "Best spot right now?"
Ranks every spot in your region by current conditions. Mention "weekend" to include spots further from home.
> "When should I surf this week?"
Scans the next few days across all your spots and finds the best windows — the combination of spot + time where conditions peak.
### Know your spots
> "What works best at Supertubos?"
Pulls the Spot Guide — ideal swell direction, wind, tide, size range, season, break type — from Surfline's premium data for 1,500+ spots.
> "Supertubos works best at low tide with NE wind"
Save your own preferences. They override the Spot Guide defaults, and surf-brain uses them when scoring conditions for you.
### Plan trips
> "Where should I surf next week?"
Scans top destinations worldwide and finds firing windows — scored by forecast quality, consistency, and confidence (closer days get more weight).
> "Portugal vs Indonesia?"
Side-by-side forecast comparison across regions.
> "Strike mission in northern Spain?"
Scans all spots in an area — not just the famous ones — and surfaces anything that's firing. Uses a two-step flow: preview how many spots will be checked, then fetch forecasts.
### Discover spots
> "Tell me about Uluwatu"
Search Surfline's 9,000+ spots by name.
> "Spots near Bali"
Proximity search with configurable radius.
> "All spots in Morocco"
Browse every spot in a country.
### Log sessions
> "I surfed Supertubos this morning, it was pumping, head-high, really fun"
surf-brain asks what time you paddled out, pulls the matching forecast for that hour, extracts vibe tags from your description, and logs everything. The more sessions you log, the smarter scoring gets — it learns which conditions you personally rate highly.
> "How have my sessions been?"
Review your history with conditions and ratings.
---
## How scoring works
surf-brain scores conditions 0-10 based on what actually matters to surfers:
| Factor | Weight | Why |
|--------|--------|-----|
| **Wind** | 35% | Offshore and light is king. Strong onshore kills everything. |
| **Swell period** | 25% | Long-period groundswell = powerful, clean waves. Short-period wind chop = mush. |
| **Wave size** | 25% | Need rideable waves, but more isn't always better (12ft+ gets a risk penalty). |
| **Surfline rating** | 15% | Sanity check, but not always reliable. |
**Personal scoring**: if you've logged sessions, surf-brain blends in your history — conditions similar to sessions you rated 7+ get a boost (40% conditions + 60% personal similarity).
**Wind override**: when wind is dangerously strong (sustained 16+ knots or gusts 27+ knots), surf-brain flags it regardless of what Surfline says. Surfline sometimes rates spots FAIR when they're blown out.
---
## Tools reference
| Tool | What it does |
|------|-------------|
| `get_surf_report` | Full conditions + 8-hour forecast for local spots |
| `get_wind_report` | Live sensor wind + forecast with transition alerts |
| `get_best_spot` | Rank spots by current conditions quality |
| `get_best_surf_windows` | Find optimal spot + time combos this week |
| `get_travel_recommendation` | Scan destinations worldwide for firing windows |
| `list_travel_destinations` | Browse available travel destinations |
| `compare_regions` | Side-by-side forecast comparison |
| `run_strike_mission` | Scan all spots in an area and surface anything that's firing |
| `search_spots` | Search Surfline's 9,000+ spots by name |
| `find_spots_nearby` | Proximity search around coordinates |
| `find_spots_by_country` | Browse all spots in a country |
| `get_spot_preferences` | View ideal conditions (Spot Guide + your overrides) |
| `set_spot_preferences` | Save your preferred conditions for a spot |
| `log_session` | Log a surf session with matched forecast |
| `get_session_history` | Review past sessions |
| `set_home_location` | Set your home surf region |
| `add_surf_region` | Add an additional home region |
| `add_favorite_region` | Add a favorite region (trip planning only, not daily checks) |
| `remove_surf_region` | Remove a configured region |
| `get_home_location` | View your configured regions |
| `set_surfline_token` | Manually set a Surfline auth token |
| `get_surfline_token_status` | Check token and credential status |
---
## How it works
surf-brain is an MCP server that connects Claude to the Surfline API. When you ask about the surf, Claude calls the right tools — which fetch real-time data, score conditions, and query your local database of spots, preferences, and session history.
```
You <-> Claude <-> surf-brain MCP Server <-> Surfline API
|
SQLite (preferences, sessions)
```
All personal data stays local. The SQLite database stores your configured regions, preferences, and session history on your machine. Surfline API calls happen in parallel for speed.
