mcp-surf-forecast

This Surf Forecast MCP is a Python-based server that leverages the Open-Meteo Marine API to forecast swell height, swell period, swell direction, and wind conditions for any location worldwide. You can search by city name and the server will convert it to latitude/longitude coordinates to fetch wave and weather data. The project includes both a FastAPI backend (uvicorn) for API endpoints and an optional Streamlit frontend to visualize forecasts. To activate the MCP, run the MCP server entry point configured in the mcp.json (surf-forecast in this example) and then optionally launch the Streamlit interface to view results in a browser.

The built-in tools cover: (1) a backend API that returns current and hourly forecast data, (2) a 5-day surf forecast summarizing wave height, dominant directions, and wind, and (3) a sample response structure following Pydantic/FastAPI conventions. If you enable the frontend, Streamlit will present interactive visualizations of wave height, period, and wind alongside location details, making it easier to interpret conditions for planning sessions.

Prerequisites:

• Python 3.8+ installed on your system
• Internet access to reach the Open-Meteo API
• Optional: virtual environment tools (venv)

Step-by-step installation:

1. Clone the repository or download the MCP server files.
2. Create and activate a virtual environment (optional but recommended):
   • macOS/Linux: python -m venv .venv source .venv/bin/activate
   • Windows: python -m venv .venv\Scripts\activate
3. Install dependencies from requirements.txt: pip install -r requirements.txt
4. Run the FastAPI backend (uvicorn): uvicorn backend.main:app --reload
5. (Optional) Run the Streamlit frontend: python -m streamlit run frontend/app.py
6. Start the MCP server using the configuration provided in the README (e.g., surf-forecast): python server.py # if a custom entry is used, or start via your MCP launcher
7. Verify endpoints (e.g., local URL) and test with a city name to retrieve forecast data.

Tips and caveats:

• The MCP uses the Open-Meteo Marine API which does not require an API key, but you must have network access for real-time data.
• Ensure your Python environment has all dependencies installed as listed in requirements.txt.
• Use a virtual environment to isolate dependencies and avoid conflicts.
• If you encounter port or path issues, confirm uvicorn and Python are on your PATH and that the correct module paths are referenced in your startup commands.
• The sample mcp.json configuration in the README shows the expected server activation format; adjust the server-name and paths as needed for your deployment environment.
• The frontend (Streamlit) is optional; the backend can operate independently and serve JSON responses for integration with other clients.