Surfline

You run an MCP server that provides up-to-date surf forecasts and related data from Surfline through an MCP-compatible client. It combines current conditions, detailed swell analysis, hourly forecasts, forecaster notes, tides, and timing information into a single, easy-to-consume MCP endpoint set, so you can ask Claude or other MCP clients for comprehensive surf insight.

How to use

Connect your MCP client to the Surfline MCP Server using one of the available endpoints. You can access a hosted MCP endpoint to retrieve the full surf report, including forecaster notes, timings, tides, current conditions for all spots, swell breakdown, and 8-hour forecasts. You can also run the local development server to test everything on your machine. Once connected, you can request a complete surf report or fetch specific data like forecasts, tides, or forecaster notes as needed. For example, you can ask for a full Santa Cruz surf brief or query only the tide schedule to plan your session.

How to install

# Prerequisites
- Node.js 18+
- A Cloudflare account
- A Google Cloud project for OAuth

# Clone the project
git clone https://example.com/surfline-mcp-server.git
cd surfline-mcp-server

# Install dependencies
npm install

# Optional: Start development server locally
npm run dev

# Deploy to Cloudflare Workers (assuming you have wrangler configured)
npm run deploy

# Optional: Run MCP Inspector for testing
npx @modelcontextprotocol/inspector

Configuration, security, and setup notes

Security and authentication are handled via Google OAuth. You configure an OAuth client in Google Cloud Console, then provide the client ID, client secret, and a cookie encryption key as part of the deployment secrets. The OAuth state and token handling are managed by Durable Objects within the Cloudflare Workers environment. You also create a KV namespace to persist tokens as part of the setup.

Usage patterns and endpoints

Endpoints are exposed via a deployed MCP URL for HTTP usage and a local stdio command for development. The recommended remote endpoint you integrate with is the deployed worker URL followed by /mcp, for example: https://your-worker-name.your-subdomain.workers.dev/mcp. When testing locally, you can run the development server and connect to http://localhost:8788.

Notes on data and limitations

Data sources come from Surfline’s public endpoints and include current conditions, swell details, hourly forecasts, forecaster observations, wind data, and tides. Webcams and premium features are not available through these endpoints. All times are converted to Pacific Time.

Troubleshooting

If you cannot authenticate, verify that your Google OAuth credentials are correctly configured as environment secrets and that the redirect URIs match the deployment setup. Ensure the KV namespace is created and that the deployment framework can read the OAuth state and token data from Durable Objects. Check that the deployment URL you provide to MCP clients is reachable and that the server has the necessary permissions to access Surfline endpoints.

Available tools

get_complete_surf_report

Primary tool that returns everything in one call: forecaster notes, sunrise/sunset, tides, current conditions for all spots, swell breakdown, and 8-hour forecasts.

get_surf_forecast

Secondary tool to fetch basic spot conditions for a single location.

get_forecaster_notes

Secondary tool to fetch expert forecaster observations.

get_tides

Secondary tool to fetch tide information.

get_best_spot

Secondary tool that provides ranked spot recommendations.