MCP 서버 서핑

파도와 웹을 서핑하는 사람들을 위한 MCP 서버입니다.

도표

문자 점 그리드 - 5dpi

Related MCP server: HRFCO Service

비디오 데모

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

특징

위도와 경도를 사용하여 모든 위치의 조수 정보를 가져옵니다.
날짜별 조수 쿼리 지원
만조/저조 및 관측소 정보를 포함한 자세한 조석 데이터
자동 시간대 처리(UTC)

필수 조건

파이썬 3.x
Storm Glass API 키

Storm Glass API 키 받기

스톰 글래스 방문
"무료 체험" 또는 "로그인"을 클릭하여 계정을 만드세요.
등록하면 API 키를 받게 됩니다.

API 사용 제한에 대한 참고 사항:

무료 계층: 하루 10개 요청
이용 가능한 유료 플랜:
- 소규모: 하루 500건 요청(월 €19)
- 중간: 하루 5000건 요청(월 €49)
- 대규모: 하루 25,000건의 요청(월 €129)
- Enterprise: 맞춤형 플랜 이용 가능

사용 요건에 따라 플랜을 선택하세요. 무료 티어는 테스트 및 개인 사용에 적합합니다.

설치

저장소를 복제합니다.

지엑스피1

uv를 사용하여 종속성을 설치합니다.

uv sync

참고: 이 프로젝트는 종속성 관리를 위해 pyproject.toml 사용하므로 pip 대신 uv 사용합니다.

MCP 서버로 구성

이 도구를 MCP 서버로 추가하려면 Claude 데스크톱 구성 파일을 수정해야 합니다. 이 구성에는 Storm Glass API 키가 포함되어 있으므로 별도로 설정할 필요가 없습니다.

구성 파일 위치는 운영 체제에 따라 다릅니다.

MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
윈도우: %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" } } }

⚠️ 중요:

YOUR_USERNAME 실제 시스템 사용자 이름으로 바꾸세요.
your_api_key_here 실제 Storm Glass API 키로 바꾸세요.
디렉토리 경로가 로컬 설치와 일치하는지 확인하세요.

전개

건물

패키지를 준비하려면:

종속성 동기화 및 잠금 파일 업데이트:

uv sync

패키지 빌드:

uv build

이렇게 하면 dist/ 디렉토리에 배포판이 생성됩니다.

디버깅

MCP 서버는 stdio를 통해 실행되므로 디버깅이 어려울 수 있습니다. 최상의 디버깅 환경을 위해서는 MCP Inspector 사용을 강력히 권장합니다.

다음 명령을 사용하여 MCP 검사기를 시작할 수 있습니다.

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

Inspector를 실행하면 브라우저에서 접근하여 디버깅을 시작할 수 있는 URL이 표시됩니다.

검사관은 다음을 제공합니다.

실시간 요청/응답 모니터링
입력/출력 검증
오류 추적
성과 지표

용법

이 서비스는 조수 정보를 얻기 위한 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에게 요청할 때 이 정보도 함께 제공될 수 있습니다.)