Hands-on-MCP
If you are the rightful owner of Hands-on-MCP and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
This repository contains a simple MCP server that provides weather alert information for US states, leveraging the National Weather Service (NWS) API.
MCP US Weather Client/Server
This was my first encounter with hands on implementation of MCP, i really liked it & i firmly believe MCP is here to stay, i have to implement some more projects to get more more better understanding about the overall ecosystem,About the repository, This repository contains a simple MCP (Model Context Protocol) server that provides weather alert information for US states, leveraging the National Weather Service (NWS) API. It also includes an example client application that demonstrates how to interact with the MCP server using the mcp_use library and Langchain.
Features
- Weather Alerts: Fetches and formats active weather alerts for a specified US state.
- MCP Integration: Demonstrates how to build an MCP server using the
fastmcplibrary. - Client Example: Provides a client application that uses the server and integrates conversation memory.
- Langchain Integration: Example showcases LLM integration.
Architecture
graph LR
%% MCP System
subgraph MCP_System
A[Client: client.py]
B[MCP Agent: mcp_use.MCPAgent]
C[MCP Client: mcp_use.MCPClient]
D[FastMCP Server: weather.py]
E[NWS API: api.weather.gov]
A --> B
B --> C
C --> D
D --> E
end
%% Data Flow
subgraph Data_Flow
F[User Input]
F --> A
E -->|Geo+JSON| D
D -->|Weather Data| B
B -->|LLM Interaction| F
end
%% Styling with visible text
classDef client fill:#f9f,stroke:#333,color:#000,font-weight:bold;
classDef agent fill:#ccf,stroke:#333,color:#000,font-weight:bold;
classDef server fill:#fcc,stroke:#333,color:#000,font-weight:bold;
classDef api fill:#ffc,stroke:#333,color:#000,font-weight:bold;
classDef user fill:#cfc,stroke:#333,color:#000,font-weight:bold;
class A client;
class B,C agent;
class D server;
class E api;
class F user;
%% Link styling
linkStyle default stroke:#000,stroke-width:2px;
Prerequisites
Before running the server and client, ensure you have the following installed:
- Python 3.7+
- uv (recommended for dependency management - https://github.com/astral-sh/uv)
- Groq API key. This needs to be added to .env file.
mcp_useLibrary: Make sure you've installed this according to its documentation.
Installation
-
Clone the repository:
git clone <your_repository_url> cd <repository_directory> -
Install dependencies (using uv):
uv add -r requirements.txtThis command uses
uv pip install .to install the project and its dependencies based on thepyproject.tomlfile in the current directory. -
Create .env file: Create a
.envfile in the root directory with the following content, replacing<YOUR_GROQ_API_KEY>with your actual Groq API key:GROQ_API_KEY=<YOUR_GROQ_API_KEY>
Usage
Running the MCP Weather Server & Client
-
Start the server:
uv run mcp dev server/weather.py -
Start the Client:
uv run server/client.py
Interacting with the Client
- Type your queries at the prompt. For example: "Get weather alerts for CA, NY or NJ etc".
- Type
exitorquitto end the conversation. - Type
clearto clear the conversation history.
Example Interactions
The agent will then use the get_alerts tool to fetch weather alerts for California and provide you with the formatted results.
The agent will then use the get_config tool to fetch the resource.
Configuration
server/weather.json
This configuration file describes the tools and resources exposed by the MCP server. It's crucial that this file accurately reflects the definitions in your weather.py file. See the mcp_use documentation for details on the format of this file. The default configuration is in the server folder.
Environment Variables
The client application uses environment variables, specifically GROQ_API_KEY, to authenticate with the Groq API. Make sure to set these variables before running the client. You can set those variables using the .env file.
Output
- Console Output: This screenshot shows the typical output of the client application during a conversation, demonstrating how the agent interacts with the MCP server and utilizes the
get_alertstool.
- MCP Inspector: This screenshot shows the typical weather.json used with the MCP Inspector
Contact
For any inquiries or support, please reach out:
- Email:
- Personal Website: aiankit.com
