mcp-weather-server
by FarahSaeed
README.md
\# Weather Intelligence MCP Server + Agent
\## Overview
This project implements a weather-intelligence MCP server using \*\*FastMCP\*\*, a weather API adapter, and a Databricks Agent Bricks agent.
The MCP server exposes weather tools that allow an agent to answer natural-language questions about current conditions, forecasts, and simple weather-based travel recommendations.
The application is deployed as a \*\*Databricks App\*\* using the MCP Server Starter application type.
\## Architecture
```text
  ┌──────────────────────────┐
  │ Databricks Agent │
  │ / Agent Bricks │
  └────────────┬─────────────┘
  │
  │ MCP
  ▼
  ┌──────────────────────────┐
  │ Weather MCP Server │
  │ weather\_mcp\_server.py │
  │ │
  │ @mcp.tool │
  │ @mcp.tool │
  │ @mcp.tool │
  └────────────┬─────────────┘
  │
  ▼
  ┌──────────────────────────┐
  │ WeatherAdapter │
  │ weather\_adapter.py │
  │ │
  │ HTTP / parsing / logic │
  └────────────┬─────────────┘
  │
  ▼
  ┌──────────────────────────┐
  │ National Weather Service │
  │ API (NWS) │
  └──────────────────────────┘
```
The MCP tool functions are intentionally thin. All weather API calls and response parsing are handled by `weather\_adapter.py`.
\---
\# Weather Data Source
The primary weather data source is the \*\*National Weather Service (NWS) API\*\*.
NWS was selected because:
\* It is free.
\* It does not require an API key.
\* It is an official US government weather data source.
\* It provides current observations and forecasts.
\* It provides reliable forecast and weather information for US locations.
The application currently focuses on US locations because the NWS API is US-specific.
Location resolution is handled before querying NWS so that a city/state such as:
```text
Chicago, IL
```
can be converted into latitude and longitude.
\---
\# MCP Tools
The MCP server exposes three tools through FastMCP.
These tools are defined in:
```text
weather\_mcp\_server.py
```
Each function decorated with `@mcp.tool` becomes an MCP tool that can be discovered and called by an MCP client or Agent Bricks agent.
\## 1. `get\_current\_weather`
Returns the current weather conditions for a US location.
\### Arguments
```text
location
```
US city and state, for example:
```text
Chicago, IL
```
\### Returns
The tool returns information including:
\* Temperature
\* Current weather conditions
\* Humidity
\* Wind
\* Observation timestamp
\### Example question
```text
What is the weather like in Chicago right now?
```
The agent should call:
```text
get\_current\_weather("Chicago, IL")
```
\---
\## 2. `get\_forecast`
Returns a weather forecast for a US location.
\### Arguments
```text
location
days
```
Example:
```text
location = "Chicago, IL"
days = 3
```
The `days` parameter supports values from 1 through 7.
\### Returns
The tool provides forecast information including:
\* Forecast periods
\* Temperature
\* Conditions
\* Wind
\* Probability of precipitation
\### Example question
```text
What will the weather be like in Chicago over the next three days?
```
The agent should call:
```text
get\_forecast("Chicago, IL", 3)
```
\---
\## 3. `get\_travel\_recommendation`
Provides a simple weather-based travel recommendation.
\### Arguments
```text
location
date
```
The date must use:
```text
YYYY-MM-DD
```
Example:
```text
location = "Chicago, IL"
date = "2026-08-12"
```
\### Decision Rules
The recommendation tool applies simple rules to the forecast:
| Weather condition | Recommendation |
| -------------------------------- | ------------------------------------- |
| Precipitation probability >= 40% | Bring an umbrella |
| Temperature <= 55°F | Bring a jacket |
| Temperature >= 85°F | Wear light clothing and stay hydrated |
The tool returns both the recommendation and the weather factors used to make it.
\### Example question
```text
Should I bring an umbrella to Chicago tomorrow?
```
The agent can use:
```text
get\_travel\_recommendation(
  "Chicago, IL",
  "2026-08-11"
)
```
\---
\# Tool Architecture
The MCP server keeps the tool functions separate from the weather API implementation.
```text
weather\_mcp\_server.py
  |
  | @mcp.tool
  v
weather\_adapter.py
  |
  | HTTP requests
  v
National Weather Service API
```
`weather\_mcp\_server.py` is responsible for exposing MCP tools.
`weather\_adapter.py` is responsible for:
\* Calling the weather API
\* Resolving locations
\* Parsing API responses
\* Normalizing weather data
\* Applying recommendation logic
This separation keeps the MCP tool functions small and makes the weather API implementation easier to test or replace.
\---
\# Agent Configuration
The Agent Bricks agent should be configured to use the Weather Intelligence MCP server as its external MCP tool source.
\## Tool List
The agent should have access to:
```text
get\_current\_weather
get\_forecast
get\_travel\_recommendation
```
These tools are automatically exposed by FastMCP from the `@mcp.tool` functions in `weather\_mcp\_server.py`.
The tools do not need to be duplicated as separate Python functions in the agent.
\---
\# Recommended System Prompt
The agent should be instructed to use the MCP tools for weather information instead of relying on its own knowledge.
System prompt is:
```text
You are a Weather Intelligence assistant.
Use the Weather Intelligence MCP tools to answer weather-related questions.
Available tools:
1\. get\_current\_weather
  Use this for current weather conditions.
2\. get\_forecast
  Use this for future weather forecasts and multi-day forecasts.
3\. get\_travel\_recommendation
  Use this when the user asks what they should bring, wear, or prepare for a specific date based on the weather.
Rules:
\- Always use the appropriate MCP tool when answering questions that require current or forecast weather information.
\- Do not invent or guess weather data.
\- Only provide weather information for locations that can be resolved by the weather service.
\- If a tool returns an error, clearly tell the user that the weather information could not be retrieved.
\- For forecast questions, use get\_forecast.
\- For current-weather questions, use get\_current\_weather.
\- For travel and preparation questions involving a specific date, use get\_travel\_recommendation.
\- If the user asks for information that requires multiple weather facts, call the appropriate tools and combine their results.
\- Explain recommendations clearly and identify the weather factors supporting the recommendation.
\- The travel recommendation is a simple rule-based recommendation and should not be presented as a guarantee.
```
\---
\# Error Handling
The MCP tools catch errors from the adapter and return a clean error response instead of exposing a Python stack trace.
For example:
```python
try:
  return adapter.get\_forecast(
  location,
  days,
  )
except Exception as exc:
  return {
  "error": (
  f"Unable to retrieve forecast "
  f"for {location}: {exc}"
  )
  }
```
This allows the agent to respond appropriately when:
\* A location cannot be resolved.
\* The weather API is unavailable.
\* The API returns an unexpected response.
\* A requested forecast cannot be retrieved.
The agent should report the failure rather than fabricate an answer.
\---
\# Project Structure
```text
.
├── app.py
├── app.yaml
├── requirements.txt
├── weather\_adapter.py
├── weather\_mcp\_server.py
├── weather\_client.py
├── lakebase.py
└── ingest\_weather\_embeddings.py
```
The MCP-specific files are:
```text
weather\_mcp\_server.py
weather\_adapter.py
```
The existing weather intelligence application and Lakebase/embedding components can remain in the same repository if desired.
\---
\# MCP Server
The MCP server is implemented with FastMCP:
```python
from fastmcp import FastMCP
from weather\_adapter import WeatherAdapter
mcp = FastMCP("Weather Intelligence")
adapter = WeatherAdapter()
```
The tools are registered using:
```python
@mcp.tool
def get\_current\_weather(...):
  ...
```
```python
@mcp.tool
def get\_forecast(...):
  ...
```
```python
@mcp.tool
def get\_travel\_recommendation(...):
  ...
```
FastMCP exposes these functions through the MCP protocol.
\---
\# Databricks App Configuration
The MCP server is deployed as a Databricks App using the MCP Server Starter application type.
The application uses:
```yaml
command:
  - uvicorn
  - app:application
  - --host
  - 0.0.0.0
  - --port
  - "8000"
```
The Lakebase endpoint is configured through the application environment:
```yaml
env:
  - name: ENDPOINT\_NAME
  value: "projects/support-ticket-project/branches/production/endpoints/primary"
```
No weather API key is required because the NWS API is free and does not require authentication.
\---
\# Requirements
The main dependencies include:
```text
flask
requests
psycopg2-binary
sentence-transformers
torch
databricks-sdk>=0.81.0
fastmcp
starlette
uvicorn
asgiref
```
FastMCP and Uvicorn are used to expose the MCP server over HTTP.
\---
\# Running the Weather MCP Server
The application is started with:
```bash
uvicorn app:application --host 0.0.0.0 --port 8000
```
When deployed as a Databricks App, Databricks starts the application using the command in `app.yaml`.
The MCP endpoint must be configured correctly for the Databricks MCP client/Agent Bricks integration. The MCP client must connect to the MCP protocol endpoint, rather than a normal Flask HTML route.
\---
\# Example Agent Questions
The completed agent should be able to answer questions such as:
\### Current weather
```text
What is the weather in Chicago right now?
```
Expected tool:
```text
get\_current\_weather
```
\### Forecast
```text
What will the weather be like in Austin for the next 3 days?
```
Expected tool:
```text
get\_forecast
```
\### Recommendation
```text
Should I bring a jacket to Chicago tomorrow?
```
Expected tool:
```text
get\_travel\_recommendation
```
\### Multiple questions
```text
What is the weather in Chicago today, and should I bring an umbrella tomorrow?
```
The agent can call the appropriate tools and combine their results into one response.
\---
\# End-to-End Flow
The overall request flow is:
```text
User
  |
  v
Agent Bricks Agent
  |
  | MCP tool call
  v
Weather MCP Server
  |
  v
WeatherAdapter
  |
  v
NWS API
  |
  v
Weather result
  |
  v
MCP Server
  |
  v
Agent
  |
  v
Natural-language answer
```
The agent should never invent weather data. Weather facts should come from the MCP tool responses.
\---
\# Existing Weather Intelligence Pipeline
The repository also contains a separate weather-document and semantic-search pipeline.
That pipeline works as:
```text
NWS
 |
 v
/weather/sync
 |
 v
weather\_documents
 |
 v
/weather/embed
 |
 v
weather\_embeddings
 |
 v
/weather/search
```
The embedding model is:
```text
sentence-transformers/all-MiniLM-L6-v2
```
with:
```text
Embedding dimension: 384
Chunk size: 800 characters
Chunk overlap: 100 characters
```
The MCP server is conceptually separate from this semantic-search pipeline. The MCP tools retrieve live weather information through `WeatherAdapter`, while the existing application can continue to store and search weather documents in Lakebase.
\---
\# Known Limitations
Current limitations include:
\* Weather coverage is limited to the United States because the application uses NWS.
\* Location resolution is based on city/state input.
\* The travel recommendation uses simple fixed thresholds rather than a sophisticated prediction model.
\* Weather forecasts can change as new observations become available.
\* The MCP server currently focuses on current weather, forecasts, and recommendations.
\* The recommendation should be treated as guidance rather than a guarantee.
\* The application does not currently provide historical weather analysis through MCP.
\---
\# Possible Future Improvements
Given more development time, the following could be added:
\* Severe weather alert MCP tool.
\* Historical weather tool.
\* International weather support using Open-Meteo.
\* Weather comparison across multiple cities.
\* More sophisticated recommendation logic.
\* Caching to reduce repeated API requests.
\* Additional validation for location and date inputs.
\* Automated MCP integration tests.
\* A dashboard showing agent queries and weather recommendations.
\---
This server cannot be deployed
Maintenance
ActivitySlowing
ResponsivenessNo issues