Surf (Stormglass) MCP server for AI agents

The Surf MCP Server provides a convenient way to fetch tide information for any location using the Model Context Protocol. This tool integrates with Claude AI to deliver accurate tide data based on latitude, longitude, and date specifications.

Features

Fetch tide information for any location using latitude and longitude
Support for date-specific tide queries
Detailed tide data including high/low tides and station information
Automatic time zone handling (UTC)

Prerequisites

Python 3.x
Storm Glass API key

Getting Your Storm Glass API Key

Visit Storm Glass
Click "Try for Free" or "Sign In" to create an account
Once registered, you'll receive your API key

Note on API Usage Limits:

Free tier: 10 requests per day
Paid plans available:
- Small: 500 requests/day (€19/month)
- Medium: 5000 requests/day (€49/month)
- Large: 25,000 requests/day (€129/month)
- Enterprise: Custom plans available

Installation

Clone the repository:

git clone https://github.com/ravinahp/surf-mcp.git
cd surf-mcp

Install dependencies using uv:

uv sync

Configure as MCP Server

To add this tool as an MCP server, you'll need to modify your Claude desktop configuration file:

MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

Add the following configuration to your JSON file:

{
    "surf-mcp": {
        "command": "uv",
        "args": [
            "--directory",
            "/Users/YOUR_USERNAME/Code/surf-mcp",
            "run",
            "surf-mcp"
        ],
        "env": {
            "STORMGLASS_API_KEY": "your_api_key_here"
        }
    }
}

⚠️ Important:

Replace YOUR_USERNAME with your actual system username
Replace your_api_key_here with your actual Storm Glass API key
Make sure the directory path matches your local installation

Usage

The service provides a FastMCP tool for getting tide information:

@mcp.tool()
async def get_tides(latitude: float, longitude: float, date: str) -> str:
    """Get tide information for a specific location and date."""

Parameters:

latitude: Float value representing the location's latitude
longitude: Float value representing the location's longitude
date: Date string in YYYY-MM-DD format

Example Response:

Tide Times:
Time: 2024-01-20T00:30:00+00:00 (UTC)
Type: HIGH tide
Height: 1.52m

Time: 2024-01-20T06:45:00+00:00 (UTC)
Type: LOW tide
Height: 0.25m

Station Information:
Name: Sample Station
Distance: 20.5km from requested location

Use Cases

Finding the Best Surf Time

You can use this tool to determine the optimal surfing time at your favorite beach & the closest station. Generally, the best surfing conditions are during incoming (rising) tides, about 2 hours before high tide.

Example prompt to Claude: Ask Claude to check the tide information for your favorite surfing location by providing the coordinates and date.

Note: Different beaches may have different optimal tide conditions based on their specific geography and break type. The station distance information should be considered alongside tide information, as longer station distances may result in less accurate predictions.

Debugging

For debugging assistance, use the MCP Inspector:

npx @modelcontextprotocol/inspector uv --directory /path/to/surf-mcp run surf-mcp

The Inspector will display a URL to access in your browser for monitoring:

Real-time request/response data
Input/output validation
Error tracking
Performance metrics

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "surf-mcp" '{"command":"uv","args":["--directory","/Users/YOUR_USERNAME/Code/surf-mcp","run","surf-mcp"],"env":{"STORMGLASS_API_KEY":"your_api_key_here"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "surf-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/Users/YOUR_USERNAME/Code/surf-mcp",
                "run",
                "surf-mcp"
            ],
            "env": {
                "STORMGLASS_API_KEY": "your_api_key_here"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "surf-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/Users/YOUR_USERNAME/Code/surf-mcp",
                "run",
                "surf-mcp"
            ],
            "env": {
                "STORMGLASS_API_KEY": "your_api_key_here"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect