Surf MCP Server

Surf MCP Server

サーフィンとウェブを楽しむ人向けのMCP サーバーです。

図

動画デモ

https://github.com/user-attachments/assets/0a4453e2-66df-4bf5-8366-8538cda366ed

機能

• 緯度と経度を使って、任意の場所の潮汐情報を取得します
• 日付を指定した潮汐情報のクエリに対応しています
• 満潮・干潮や観測所情報など、詳細な潮汐データを提供します
• タイムゾーンを自動的に処理します（UTC）

前提条件

• Python 3.x
• Storm Glass API キー

Storm Glass API キーの取得方法

1. Storm Glass にアクセスします
2. 「Try for Free」または「Sign In」をクリックしてアカウントを作成します
3. 登録すると、API キーが発行されます

API の使用制限に関する注意：

• 無料プラン：1 日あたり 10 件のリクエスト
• 有料プラン：
  • Small：1 日あたり 500 件のリクエスト（€19/月）
  • Medium：1 日あたり 5000 件のリクエスト（€49/月）
  • Large：1 日あたり 25,000 件のリクエスト（€129/月）
  • Enterprise：カスタムプランを利用できます

使用量に応じてプランを選択してください。無料プランはテストや個人利用に適しています。

インストール

1. リポジトリをクローンします：

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

2. uv を使って依存関係をインストールします：

uv sync

注：このプロジェクトでは依存関係の管理に pyproject.toml を使用しているため、pip ではなく uv を使用します。

MCP サーバーとして設定する

このツールをMCP サーバーとして追加するには、Claude のデスクトップ設定ファイルを変更する必要があります。この設定には Storm Glass API キーが含まれるため、別途設定する必要はありません。

設定ファイルの場所は、オペレーティングシステムによって異なります：

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

次の設定を JSON ファイルに追加します：

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

⚠️ 重要：

1. YOUR_USERNAME を実際のシステムユーザー名に置き換えます
2. your_api_key_here を実際の Storm Glass API キーに置き換えます
3. ディレクトリのパスがローカルのインストール先と一致していることを確認します

デプロイ

ビルド

パッケージを準備します：

1. 依存関係を同期し、ロックファイルを更新します：

uv sync

2. パッケージをビルドします：

uv build

これにより、dist/ ディレクトリに配布物が作成されます。

デバッグ

MCP サーバーは stdio 経由で実行されるため、デバッグが難しい場合があります。最適なデバッグ環境を利用するには、MCP Inspector の使用を強くおすすめします。

次のコマンドで MCP Inspector を起動できます：

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

起動すると、ブラウザーでアクセスできる URL が Inspector に表示され、デバッグを開始できます。

Inspector では次のことができます：

• リクエストとレスポンスをリアルタイムで監視
• 入力と出力を検証
• エラーを追跡
• パフォーマンス指標を確認

使用方法

このサービスでは、潮汐情報を取得するための FastMCP ツールを提供します：

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

パラメーター：

• latitude：場所の緯度を表す浮動小数点数
• longitude：場所の経度を表す浮動小数点数
• date：YYYY-MM-DD 形式の日付文字列

レスポンスの例：

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

使用例

例 #1：サーフィンに最適な時間を見つける

このツールを使って、お気に入りのビーチと最寄りの観測所でサーフィンに最適な時間を特定できます。一般的に、サーフィンに最適な条件は潮が満ちている時間帯で、満潮の約 2 時間前です。

Claude へのプロンプトの例：

注：ビーチごとに地形やブレイクの種類が異なるため、最適な潮汐条件も異なる場合があります。このツールは観測所までの距離も提供するため、潮汐情報とあわせて考慮してください（つまり、観測所までの距離が長いほど、情報の不正確さが増す可能性があります。プロンプトで Claude にこれについて尋ねることもできます）。

エラー処理

このサービスには、次のような状況に対応する堅牢なエラー処理が含まれています：

• API リクエストの失敗
• 無効な座標
• API キーの欠落または無効
• ネットワークのタイムアウト