1122 lines
No EOL
30 KiB
Text
1122 lines
No EOL
30 KiB
Text
---
|
||
title: "Quickstart"
|
||
description: "Get started with building your first MCP server and connecting it to a host"
|
||
---
|
||
|
||
In this tutorial, we'll build a simple MCP weather server and connect it to a host, Claude for Desktop. We'll start with a basic setup, and then progress to more complex use cases.
|
||
|
||
### What we'll be building
|
||
|
||
Many LLMs (including Claude) do not currently have the ability to fetch the forecast and severe weather alerts. Let's use MCP to solve that!
|
||
|
||
We'll build a server that exposes two tools: `get-alerts` and `get-forecast`. Then we'll connect the server to an MCP host (in this case, Claude for Desktop):
|
||
|
||
<Frame>
|
||
<img src="/images/weather-alerts.png" />
|
||
</Frame>
|
||
<Frame>
|
||
<img src="/images/current-weather.png" />
|
||
</Frame>
|
||
|
||
<Note>
|
||
Servers can connect to any client. We've chosen Claude for Desktop here for simplicity, but we also have guides on [building your own client](/tutorials/building-a-client) as well as a [list of other clients here](/clients).
|
||
</Note>
|
||
|
||
<Accordion title="Why Claude for Desktop and not Claude.ai?">
|
||
Because servers are locally run, MCP currently only supports desktop hosts. Remote hosts are in active development.
|
||
</Accordion>
|
||
|
||
### Core MCP Concepts
|
||
|
||
MCP servers can provide three main types of capabilities:
|
||
|
||
1. **Resources**: File-like data that can be read by clients (like API responses or file contents)
|
||
2. **Tools**: Functions that can be called by the LLM (with user approval)
|
||
3. **Prompts**: Pre-written templates that help users accomplish specific tasks
|
||
|
||
This tutorial will primarily focus on tools.
|
||
|
||
<Tabs>
|
||
<Tab title='Python'>
|
||
|
||
Let's get started with building our weather server! [You can find the complete code for what we'll be building here.](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/weather-server-python)
|
||
|
||
### Prerequisite knowledge
|
||
|
||
This quickstart assumes you have familiarity with:
|
||
- Python
|
||
- LLMs like Claude
|
||
|
||
### System requirements
|
||
|
||
For Python, make sure you have Python 3.9 or higher installed.
|
||
|
||
### Set up your environment
|
||
|
||
First, let's install `uv` and set up our Python project and environment:
|
||
|
||
<CodeGroup>
|
||
|
||
```bash MacOS/Linux
|
||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||
```
|
||
|
||
```powershell Windows
|
||
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
|
||
```
|
||
|
||
</CodeGroup>
|
||
|
||
Make sure to restart your terminal afterwards to ensure that the `uv` command gets picked up.
|
||
|
||
Now, let's create and set up our project:
|
||
|
||
<CodeGroup>
|
||
```bash MacOS/Linux
|
||
# Create a new directory for our project
|
||
uv init weather
|
||
cd weather
|
||
|
||
# Create virtual environment and activate it
|
||
uv venv
|
||
source .venv/bin/activate
|
||
|
||
# Install dependencies
|
||
uv add mcp httpx
|
||
|
||
# Remove template file
|
||
rm hello.py
|
||
|
||
# Create our files
|
||
mkdir -p src/weather
|
||
touch src/weather/__init__.py
|
||
touch src/weather/server.py
|
||
```
|
||
|
||
```powershell Windows
|
||
# Create a new directory for our project
|
||
uv init weather
|
||
cd weather
|
||
|
||
# Create virtual environment and activate it
|
||
uv venv
|
||
.venv\Scripts\activate
|
||
|
||
# Install dependencies
|
||
uv add mcp httpx
|
||
|
||
# Clean up boilerplate code
|
||
rm hello.py
|
||
|
||
# Create our files
|
||
md src
|
||
md src\weather
|
||
new-item src\weather\__init__.py
|
||
new-item src\weather\server.py
|
||
```
|
||
</CodeGroup>
|
||
|
||
Add this code to `pyproject.toml`:
|
||
|
||
```toml
|
||
...rest of config
|
||
|
||
[build-system]
|
||
requires = [ "hatchling",]
|
||
build-backend = "hatchling.build"
|
||
|
||
[project.scripts]
|
||
weather = "weather:main"
|
||
```
|
||
|
||
Add this code to `__init__.py`:
|
||
|
||
```python src/weather/__init__.py
|
||
from . import server
|
||
import asyncio
|
||
|
||
def main():
|
||
"""Main entry point for the package."""
|
||
asyncio.run(server.main())
|
||
|
||
# Optionally expose other important items at package level
|
||
__all__ = ['main', 'server']
|
||
```
|
||
|
||
Now let's dive into building your server.
|
||
|
||
## Building your server
|
||
|
||
### Importing packages
|
||
|
||
Add these to the top of your `server.py`:
|
||
```python
|
||
from typing import Any
|
||
import asyncio
|
||
import httpx
|
||
from mcp.server.models import InitializationOptions
|
||
import mcp.types as types
|
||
from mcp.server import NotificationOptions, Server
|
||
import mcp.server.stdio
|
||
```
|
||
|
||
### Setting up the instance
|
||
|
||
Then initialize the server instance and the base URL for the NWS API:
|
||
|
||
```python
|
||
NWS_API_BASE = "https://api.weather.gov"
|
||
USER_AGENT = "weather-app/1.0"
|
||
|
||
server = Server("weather")
|
||
```
|
||
|
||
### Implementing tool listing
|
||
|
||
We need to tell clients what tools are available. The `list_tools()` decorator registers this handler:
|
||
|
||
```python
|
||
@server.list_tools()
|
||
async def handle_list_tools() -> list[types.Tool]:
|
||
"""
|
||
List available tools.
|
||
Each tool specifies its arguments using JSON Schema validation.
|
||
"""
|
||
return [
|
||
types.Tool(
|
||
name="get-alerts",
|
||
description="Get weather alerts for a state",
|
||
inputSchema={
|
||
"type": "object",
|
||
"properties": {
|
||
"state": {
|
||
"type": "string",
|
||
"description": "Two-letter state code (e.g. CA, NY)",
|
||
},
|
||
},
|
||
"required": ["state"],
|
||
},
|
||
),
|
||
types.Tool(
|
||
name="get-forecast",
|
||
description="Get weather forecast for a location",
|
||
inputSchema={
|
||
"type": "object",
|
||
"properties": {
|
||
"latitude": {
|
||
"type": "number",
|
||
"description": "Latitude of the location",
|
||
},
|
||
"longitude": {
|
||
"type": "number",
|
||
"description": "Longitude of the location",
|
||
},
|
||
},
|
||
"required": ["latitude", "longitude"],
|
||
},
|
||
),
|
||
]
|
||
|
||
```
|
||
|
||
This defines our two tools: `get-alerts` and `get-forecast`.
|
||
|
||
### Helper functions
|
||
|
||
Next, let's add our helper functions for querying and formatting the data from the National Weather Service API:
|
||
|
||
```python
|
||
async def make_nws_request(client: httpx.AsyncClient, url: str) -> dict[str, Any] | None:
|
||
"""Make a request to the NWS API with proper error handling."""
|
||
headers = {
|
||
"User-Agent": USER_AGENT,
|
||
"Accept": "application/geo+json"
|
||
}
|
||
|
||
try:
|
||
response = await client.get(url, headers=headers, timeout=30.0)
|
||
response.raise_for_status()
|
||
return response.json()
|
||
except Exception:
|
||
return None
|
||
|
||
def format_alert(feature: dict) -> str:
|
||
"""Format an alert feature into a concise string."""
|
||
props = feature["properties"]
|
||
return (
|
||
f"Event: {props.get('event', 'Unknown')}\n"
|
||
f"Area: {props.get('areaDesc', 'Unknown')}\n"
|
||
f"Severity: {props.get('severity', 'Unknown')}\n"
|
||
f"Status: {props.get('status', 'Unknown')}\n"
|
||
f"Headline: {props.get('headline', 'No headline')}\n"
|
||
"---"
|
||
)
|
||
```
|
||
|
||
### Implementing tool execution
|
||
|
||
The tool execution handler is responsible for actually executing the logic of each tool. Let's add it:
|
||
|
||
```python
|
||
@server.call_tool()
|
||
async def handle_call_tool(
|
||
name: str, arguments: dict | None
|
||
) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
|
||
"""
|
||
Handle tool execution requests.
|
||
Tools can fetch weather data and notify clients of changes.
|
||
"""
|
||
if not arguments:
|
||
raise ValueError("Missing arguments")
|
||
|
||
if name == "get-alerts":
|
||
state = arguments.get("state")
|
||
if not state:
|
||
raise ValueError("Missing state parameter")
|
||
|
||
# Convert state to uppercase to ensure consistent format
|
||
state = state.upper()
|
||
if len(state) != 2:
|
||
raise ValueError("State must be a two-letter code (e.g. CA, NY)")
|
||
|
||
async with httpx.AsyncClient() as client:
|
||
alerts_url = f"{NWS_API_BASE}/alerts?area={state}"
|
||
alerts_data = await make_nws_request(client, alerts_url)
|
||
|
||
if not alerts_data:
|
||
return [types.TextContent(type="text", text="Failed to retrieve alerts data")]
|
||
|
||
features = alerts_data.get("features", [])
|
||
if not features:
|
||
return [types.TextContent(type="text", text=f"No active alerts for {state}")]
|
||
|
||
# Format each alert into a concise string
|
||
formatted_alerts = [format_alert(feature) for feature in features[:20]] # only take the first 20 alerts
|
||
alerts_text = f"Active alerts for {state}:\n\n" + "\n".join(formatted_alerts)
|
||
|
||
return [
|
||
types.TextContent(
|
||
type="text",
|
||
text=alerts_text
|
||
)
|
||
]
|
||
elif name == "get-forecast":
|
||
try:
|
||
latitude = float(arguments.get("latitude"))
|
||
longitude = float(arguments.get("longitude"))
|
||
except (TypeError, ValueError):
|
||
return [types.TextContent(
|
||
type="text",
|
||
text="Invalid coordinates. Please provide valid numbers for latitude and longitude."
|
||
)]
|
||
|
||
# Basic coordinate validation
|
||
if not (-90 <= latitude <= 90) or not (-180 <= longitude <= 180):
|
||
return [types.TextContent(
|
||
type="text",
|
||
text="Invalid coordinates. Latitude must be between -90 and 90, longitude between -180 and 180."
|
||
)]
|
||
|
||
async with httpx.AsyncClient() as client:
|
||
# First get the grid point
|
||
lat_str = f"{latitude}"
|
||
lon_str = f"{longitude}"
|
||
points_url = f"{NWS_API_BASE}/points/{lat_str},{lon_str}"
|
||
points_data = await make_nws_request(client, points_url)
|
||
|
||
if not points_data:
|
||
return [types.TextContent(type="text", text=f"Failed to retrieve grid point data for coordinates: {latitude}, {longitude}. This location may not be supported by the NWS API (only US locations are supported).")]
|
||
|
||
# Extract forecast URL from the response
|
||
properties = points_data.get("properties", {})
|
||
forecast_url = properties.get("forecast")
|
||
|
||
if not forecast_url:
|
||
return [types.TextContent(type="text", text="Failed to get forecast URL from grid point data")]
|
||
|
||
# Get the forecast
|
||
forecast_data = await make_nws_request(client, forecast_url)
|
||
|
||
if not forecast_data:
|
||
return [types.TextContent(type="text", text="Failed to retrieve forecast data")]
|
||
|
||
# Format the forecast periods
|
||
periods = forecast_data.get("properties", {}).get("periods", [])
|
||
if not periods:
|
||
return [types.TextContent(type="text", text="No forecast periods available")]
|
||
|
||
# Format each period into a concise string
|
||
formatted_forecast = []
|
||
for period in periods:
|
||
forecast_text = (
|
||
f"{period.get('name', 'Unknown')}:\n"
|
||
f"Temperature: {period.get('temperature', 'Unknown')}°{period.get('temperatureUnit', 'F')}\n"
|
||
f"Wind: {period.get('windSpeed', 'Unknown')} {period.get('windDirection', '')}\n"
|
||
f"{period.get('shortForecast', 'No forecast available')}\n"
|
||
"---"
|
||
)
|
||
formatted_forecast.append(forecast_text)
|
||
|
||
forecast_text = f"Forecast for {latitude}, {longitude}:\n\n" + "\n".join(formatted_forecast)
|
||
|
||
return [types.TextContent(
|
||
type="text",
|
||
text=forecast_text
|
||
)]
|
||
else:
|
||
raise ValueError(f"Unknown tool: {name}")
|
||
```
|
||
|
||
### Running the server
|
||
|
||
Finally, implement the main function to run the server:
|
||
|
||
```python
|
||
async def main():
|
||
# Run the server using stdin/stdout streams
|
||
async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
|
||
await server.run(
|
||
read_stream,
|
||
write_stream,
|
||
InitializationOptions(
|
||
server_name="weather",
|
||
server_version="0.1.0",
|
||
capabilities=server.get_capabilities(
|
||
notification_options=NotificationOptions(),
|
||
experimental_capabilities={},
|
||
),
|
||
),
|
||
)
|
||
|
||
# This is needed if you'd like to connect to a custom client
|
||
if __name__ == "__main__":
|
||
asyncio.run(main())
|
||
```
|
||
|
||
Your server is complete! Run `uv run src/weather/server.py` to confirm that everything's working.
|
||
|
||
Let's now test your server from an existing MCP host, Claude for Desktop.
|
||
|
||
## Testing your server with Claude for Desktop
|
||
|
||
<Note>
|
||
Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/tutorials/building-a-client) tutorial to build an MCP client that connects to the server we just built.
|
||
</Note>
|
||
|
||
First, make sure you have Claude for Desktop installed. [You can install the latest version
|
||
here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
|
||
|
||
We'll need to configure Claude for Desktop for whichever MCP servers you want to use. To do this, open your Claude for Desktop App configuration at `~/Library/Application Support/Claude/claude_desktop_config.json` in a text editor. Make sure to create the file if it doesn't exist.
|
||
|
||
For example, if you have [VS Code](https://code.visualstudio.com/) installed:
|
||
|
||
<Tabs>
|
||
<Tab title="MacOS/Linux">
|
||
```bash
|
||
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
|
||
```
|
||
</Tab>
|
||
<Tab title="Windows">
|
||
```powershell
|
||
code $env:AppData\Claude\claude_desktop_config.json
|
||
```
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
You'll then add your servers in the `mcpServers` key. The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured.
|
||
|
||
In this case, we'll add our single weather server like so:
|
||
|
||
<Tabs>
|
||
<Tab title="MacOS/Linux">
|
||
```json Python
|
||
{
|
||
"mcpServers": {
|
||
"weather": {
|
||
"command": "uv",
|
||
"args": [
|
||
"--directory",
|
||
"/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",
|
||
"run",
|
||
"weather"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
</Tab>
|
||
<Tab title="Windows">
|
||
```json Python
|
||
{
|
||
"mcpServers": {
|
||
"weather": {
|
||
"command": "uv",
|
||
"args": [
|
||
"--directory",
|
||
"C:\\ABSOLUTE\PATH\TO\PARENT\FOLDER\weather",
|
||
"run",
|
||
"weather"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
<Note>
|
||
Make sure you pass in the absolute path to your server.
|
||
</Note>
|
||
|
||
This tells Claude for Desktop:
|
||
1. There's an MCP server named "weather"
|
||
2. To launch it by running `uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather run weather`
|
||
|
||
Save the file, and restart **Claude for Desktop**.
|
||
</Tab>
|
||
|
||
<Tab title="Node">
|
||
Let's get started with building our weather server! [You can find the complete code for what we'll be building here.](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/weather-server-typescript)
|
||
|
||
### Prerequisite knowledge
|
||
|
||
This quickstart assumes you have familiarity with:
|
||
- TypeScript
|
||
- LLMs like Claude
|
||
|
||
### System requirements
|
||
|
||
For TypeScript, make sure you have the latest version of Node installed.
|
||
|
||
### Set up your environment
|
||
|
||
First, let's install Node.js and npm if you haven't already. You can download them from [nodejs.org](https://nodejs.org/).
|
||
Verify your Node.js installation:
|
||
```bash
|
||
node --version
|
||
npm --version
|
||
```
|
||
For this tutorial, you'll need Node.js version 16 or higher.
|
||
|
||
Now, let's create and set up our project:
|
||
|
||
<CodeGroup>
|
||
```bash MacOS/Linux
|
||
# Create a new directory for our project
|
||
mkdir weather
|
||
cd weather
|
||
|
||
# Initialize a new npm project
|
||
npm init -y
|
||
|
||
# Install dependencies
|
||
npm install @modelcontextprotocol/sdk zod
|
||
npm install -D @types/node typescript
|
||
|
||
# Create our files
|
||
mkdir src
|
||
touch src/index.ts
|
||
```
|
||
|
||
```powershell Windows
|
||
# Create a new directory for our project
|
||
md weather
|
||
cd weather
|
||
|
||
# Initialize a new npm project
|
||
npm init -y
|
||
|
||
# Install dependencies
|
||
npm install @modelcontextprotocol/sdk zod
|
||
npm install -D @types/node typescript
|
||
|
||
# Create our files
|
||
md src
|
||
new-item src\index.ts
|
||
```
|
||
</CodeGroup>
|
||
|
||
Update your package.json to add type: "module" and a build script:
|
||
|
||
```json package.json
|
||
{
|
||
"type": "module",
|
||
"bin": {
|
||
"weather": "./build/index.js"
|
||
},
|
||
"scripts": {
|
||
"build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
|
||
},
|
||
"files": [
|
||
"build"
|
||
],
|
||
}
|
||
```
|
||
|
||
Create a `tsconfig.json` in the root of your project:
|
||
|
||
```json tsconfig.json
|
||
{
|
||
"compilerOptions": {
|
||
"target": "ES2022",
|
||
"module": "Node16",
|
||
"moduleResolution": "Node16",
|
||
"outDir": "./build",
|
||
"rootDir": "./src",
|
||
"strict": true,
|
||
"esModuleInterop": true,
|
||
"skipLibCheck": true,
|
||
"forceConsistentCasingInFileNames": true
|
||
},
|
||
"include": ["src/**/*"],
|
||
"exclude": ["node_modules"]
|
||
}
|
||
```
|
||
|
||
Now let's dive into building your server.
|
||
|
||
## Building your server
|
||
|
||
### Importing packages
|
||
|
||
Add these to the top of your `src/index.ts`:
|
||
|
||
```typescript
|
||
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
|
||
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
||
import {
|
||
CallToolRequestSchema,
|
||
ListToolsRequestSchema,
|
||
} from "@modelcontextprotocol/sdk/types.js";
|
||
import { z } from "zod";
|
||
```
|
||
|
||
### Setting up the instance
|
||
|
||
Then initialize the NWS API base URL, validation schemas, and server instance:
|
||
|
||
```typescript
|
||
const NWS_API_BASE = "https://api.weather.gov";
|
||
const USER_AGENT = "weather-app/1.0";
|
||
|
||
// Define Zod schemas for validation
|
||
const AlertsArgumentsSchema = z.object({
|
||
state: z.string().length(2),
|
||
});
|
||
|
||
const ForecastArgumentsSchema = z.object({
|
||
latitude: z.number().min(-90).max(90),
|
||
longitude: z.number().min(-180).max(180),
|
||
});
|
||
|
||
// Create server instance
|
||
const server = new Server(
|
||
{
|
||
name: "weather",
|
||
version: "1.0.0",
|
||
},
|
||
{
|
||
capabilities: {
|
||
tools: {},
|
||
},
|
||
}
|
||
);
|
||
```
|
||
|
||
### Implementing tool listing
|
||
|
||
We need to tell clients what tools are available. This `server.setRequestHandler` call will register this list for us:
|
||
|
||
```typescript
|
||
// List available tools
|
||
server.setRequestHandler(ListToolsRequestSchema, async () => {
|
||
return {
|
||
tools: [
|
||
{
|
||
name: "get-alerts",
|
||
description: "Get weather alerts for a state",
|
||
inputSchema: {
|
||
type: "object",
|
||
properties: {
|
||
state: {
|
||
type: "string",
|
||
description: "Two-letter state code (e.g. CA, NY)",
|
||
},
|
||
},
|
||
required: ["state"],
|
||
},
|
||
},
|
||
{
|
||
name: "get-forecast",
|
||
description: "Get weather forecast for a location",
|
||
inputSchema: {
|
||
type: "object",
|
||
properties: {
|
||
latitude: {
|
||
type: "number",
|
||
description: "Latitude of the location",
|
||
},
|
||
longitude: {
|
||
type: "number",
|
||
description: "Longitude of the location",
|
||
},
|
||
},
|
||
required: ["latitude", "longitude"],
|
||
},
|
||
},
|
||
],
|
||
};
|
||
});
|
||
```
|
||
|
||
This defines our two tools: `get-alerts` and `get-forecast`.
|
||
|
||
### Helper functions
|
||
|
||
Next, let's add our helper functions for querying and formatting the data from the National Weather Service API:
|
||
|
||
```typescript
|
||
// Helper function for making NWS API requests
|
||
async function makeNWSRequest<T>(url: string): Promise<T | null> {
|
||
const headers = {
|
||
"User-Agent": USER_AGENT,
|
||
Accept: "application/geo+json",
|
||
};
|
||
|
||
try {
|
||
const response = await fetch(url, { headers });
|
||
if (!response.ok) {
|
||
throw new Error(`HTTP error! status: ${response.status}`);
|
||
}
|
||
return (await response.json()) as T;
|
||
} catch (error) {
|
||
console.error("Error making NWS request:", error);
|
||
return null;
|
||
}
|
||
}
|
||
|
||
interface AlertFeature {
|
||
properties: {
|
||
event?: string;
|
||
areaDesc?: string;
|
||
severity?: string;
|
||
status?: string;
|
||
headline?: string;
|
||
};
|
||
}
|
||
|
||
// Format alert data
|
||
function formatAlert(feature: AlertFeature): string {
|
||
const props = feature.properties;
|
||
return [
|
||
`Event: ${props.event || "Unknown"}`,
|
||
`Area: ${props.areaDesc || "Unknown"}`,
|
||
`Severity: ${props.severity || "Unknown"}`,
|
||
`Status: ${props.status || "Unknown"}`,
|
||
`Headline: ${props.headline || "No headline"}`,
|
||
"---",
|
||
].join("\n");
|
||
}
|
||
|
||
interface ForecastPeriod {
|
||
name?: string;
|
||
temperature?: number;
|
||
temperatureUnit?: string;
|
||
windSpeed?: string;
|
||
windDirection?: string;
|
||
shortForecast?: string;
|
||
}
|
||
|
||
interface AlertsResponse {
|
||
features: AlertFeature[];
|
||
}
|
||
|
||
interface PointsResponse {
|
||
properties: {
|
||
forecast?: string;
|
||
};
|
||
}
|
||
|
||
interface ForecastResponse {
|
||
properties: {
|
||
periods: ForecastPeriod[];
|
||
};
|
||
}
|
||
```
|
||
|
||
### Implementing tool execution
|
||
|
||
The tool execution handler is responsible for actually executing the logic of each tool. Let's add it:
|
||
|
||
```typescript
|
||
// Handle tool execution
|
||
server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
||
const { name, arguments: args } = request.params;
|
||
|
||
try {
|
||
if (name === "get-alerts") {
|
||
const { state } = AlertsArgumentsSchema.parse(args);
|
||
const stateCode = state.toUpperCase();
|
||
|
||
const alertsUrl = `${NWS_API_BASE}/alerts?area=${stateCode}`;
|
||
const alertsData = await makeNWSRequest<AlertsResponse>(alertsUrl);
|
||
|
||
if (!alertsData) {
|
||
return {
|
||
content: [
|
||
{
|
||
type: "text",
|
||
text: "Failed to retrieve alerts data",
|
||
},
|
||
],
|
||
};
|
||
}
|
||
|
||
const features = alertsData.features || [];
|
||
if (features.length === 0) {
|
||
return {
|
||
content: [
|
||
{
|
||
type: "text",
|
||
text: `No active alerts for ${stateCode}`,
|
||
},
|
||
],
|
||
};
|
||
}
|
||
|
||
const formattedAlerts = features.map(formatAlert).slice(0, 20) // only take the first 20 alerts;
|
||
const alertsText = `Active alerts for ${stateCode}:\n\n${formattedAlerts.join(
|
||
"\n"
|
||
)}`;
|
||
|
||
return {
|
||
content: [
|
||
{
|
||
type: "text",
|
||
text: alertsText,
|
||
},
|
||
],
|
||
};
|
||
} else if (name === "get-forecast") {
|
||
const { latitude, longitude } = ForecastArgumentsSchema.parse(args);
|
||
|
||
// Get grid point data
|
||
const pointsUrl = `${NWS_API_BASE}/points/${latitude.toFixed(
|
||
4
|
||
)},${longitude.toFixed(4)}`;
|
||
const pointsData = await makeNWSRequest<PointsResponse>(pointsUrl);
|
||
|
||
if (!pointsData) {
|
||
return {
|
||
content: [
|
||
{
|
||
type: "text",
|
||
text: `Failed to retrieve grid point data for coordinates: ${latitude}, ${longitude}. This location may not be supported by the NWS API (only US locations are supported).`,
|
||
},
|
||
],
|
||
};
|
||
}
|
||
|
||
const forecastUrl = pointsData.properties?.forecast;
|
||
if (!forecastUrl) {
|
||
return {
|
||
content: [
|
||
{
|
||
type: "text",
|
||
text: "Failed to get forecast URL from grid point data",
|
||
},
|
||
],
|
||
};
|
||
}
|
||
|
||
// Get forecast data
|
||
const forecastData = await makeNWSRequest<ForecastResponse>(forecastUrl);
|
||
if (!forecastData) {
|
||
return {
|
||
content: [
|
||
{
|
||
type: "text",
|
||
text: "Failed to retrieve forecast data",
|
||
},
|
||
],
|
||
};
|
||
}
|
||
|
||
const periods = forecastData.properties?.periods || [];
|
||
if (periods.length === 0) {
|
||
return {
|
||
content: [
|
||
{
|
||
type: "text",
|
||
text: "No forecast periods available",
|
||
},
|
||
],
|
||
};
|
||
}
|
||
|
||
// Format forecast periods
|
||
const formattedForecast = periods.map((period: ForecastPeriod) =>
|
||
[
|
||
`${period.name || "Unknown"}:`,
|
||
`Temperature: ${period.temperature || "Unknown"}°${
|
||
period.temperatureUnit || "F"
|
||
}`,
|
||
`Wind: ${period.windSpeed || "Unknown"} ${
|
||
period.windDirection || ""
|
||
}`,
|
||
`${period.shortForecast || "No forecast available"}`,
|
||
"---",
|
||
].join("\n")
|
||
);
|
||
|
||
const forecastText = `Forecast for ${latitude}, ${longitude}:\n\n${formattedForecast.join(
|
||
"\n"
|
||
)}`;
|
||
|
||
return {
|
||
content: [
|
||
{
|
||
type: "text",
|
||
text: forecastText,
|
||
},
|
||
],
|
||
};
|
||
} else {
|
||
throw new Error(`Unknown tool: ${name}`);
|
||
}
|
||
} catch (error) {
|
||
if (error instanceof z.ZodError) {
|
||
throw new Error(
|
||
`Invalid arguments: ${error.errors
|
||
.map((e) => `${e.path.join(".")}: ${e.message}`)
|
||
.join(", ")}`
|
||
);
|
||
}
|
||
throw error;
|
||
}
|
||
});
|
||
```
|
||
|
||
### Running the server
|
||
|
||
Finally, implement the main function to run the server:
|
||
|
||
```typescript
|
||
// Start the server
|
||
async function main() {
|
||
const transport = new StdioServerTransport();
|
||
await server.connect(transport);
|
||
console.error("Weather MCP Server running on stdio");
|
||
}
|
||
|
||
main().catch((error) => {
|
||
console.error("Fatal error in main():", error);
|
||
process.exit(1);
|
||
});
|
||
```
|
||
|
||
Make sure to run `npm run build` to build your server! This is a very important step in getting your server to connect.
|
||
|
||
Let's now test your server from an existing MCP host, Claude for Desktop.
|
||
|
||
## Testing your server with Claude for Desktop
|
||
|
||
<Note>
|
||
Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/tutorials/building-a-client) tutorial to build an MCP client that connects to the server we just built.
|
||
</Note>
|
||
|
||
First, make sure you have Claude for Desktop installed. [You can install the latest version
|
||
here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
|
||
|
||
We'll need to configure Claude for Desktop for whichever MCP servers you want to use. To do this, open your Claude for Desktop App configuration at `~/Library/Application Support/Claude/claude_desktop_config.json` in a text editor. Make sure to create the file if it doesn't exist.
|
||
|
||
For example, if you have [VS Code](https://code.visualstudio.com/) installed:
|
||
|
||
<Tabs>
|
||
<Tab title="MacOS/Linux">
|
||
```bash
|
||
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
|
||
```
|
||
</Tab>
|
||
<Tab title="Windows">
|
||
```powershell
|
||
code $env:AppData\Claude\claude_desktop_config.json
|
||
```
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
You'll then add your servers in the `mcpServers` key. The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured.
|
||
|
||
In this case, we'll add our single weather server like so:
|
||
|
||
<Tabs>
|
||
<Tab title="MacOS/Linux">
|
||
<CodeGroup>
|
||
```json Node
|
||
{
|
||
"mcpServers": {
|
||
"weather": {
|
||
"command": "node",
|
||
"args": [
|
||
"/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
</CodeGroup>
|
||
</Tab>
|
||
<Tab title="Windows">
|
||
<CodeGroup>
|
||
```json Node
|
||
{
|
||
"mcpServers": {
|
||
"weather": {
|
||
"command": "node",
|
||
"args": [
|
||
"C:\\PATH\TO\PARENT\FOLDER\weather\build\index.js"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
</CodeGroup>
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
This tells Claude for Desktop:
|
||
1. There's an MCP server named "weather"
|
||
2. Launch it by running `node /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js`
|
||
|
||
Save the file, and restart **Claude for Desktop**.
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
### Test with commands
|
||
|
||
Let's make sure Claude for Desktop is picking up the two tools we've exposed in our `weather` server. You can do this by looking for the hammer <img src="/images/claude-desktop-mcp-hammer-icon.svg" style={{display: 'inline', margin: 0, height: '1.3em'}} /> icon:
|
||
|
||
<Frame>
|
||
<img src="/images/visual-indicator-mcp-tools.png" />
|
||
</Frame>
|
||
|
||
After clicking on the hammer icon, you should see two tools listed:
|
||
|
||
<Frame>
|
||
<img src="/images/available-mcp-tools.png" />
|
||
</Frame>
|
||
|
||
If your server isn't being picked up by Claude for Desktop, proceed to the [Troubleshooting](#troubleshooting) section for debugging tips.
|
||
|
||
If the hammer icon has shown up, you can now test your server by running the following commands in Claude for Desktop:
|
||
|
||
- What's the weather in Sacramento?
|
||
- What are the active weather alerts in Texas?
|
||
|
||
<Frame>
|
||
<img src="/images/current-weather.png" />
|
||
</Frame>
|
||
<Frame>
|
||
<img src="/images/weather-alerts.png" />
|
||
</Frame>
|
||
|
||
<Note>
|
||
Since this is the US National Weather service, the queries will only work for US locations.
|
||
</Note>
|
||
|
||
## What's happening under the hood
|
||
|
||
When you ask a question:
|
||
|
||
1. The client sends your question to Claude
|
||
2. Claude analyzes the available tools and decides which one(s) to use
|
||
3. The client executes the chosen tool(s) through the MCP server
|
||
4. The results are sent back to Claude
|
||
5. Claude formulates a natural language response
|
||
6. The response is displayed to you!
|
||
|
||
## Troubleshooting
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="Claude for Desktop Integration Issues">
|
||
**Getting logs from Claude for Desktop**
|
||
Claude.app logging related to MCP is written to log files in `~/Library/Logs/Claude`:
|
||
|
||
- `mcp.log` will contain general logging about MCP connections and connection failures.
|
||
- Files named `mcp-server-SERVERNAME.log` will contain error (stderr) logging from the named server.
|
||
|
||
You can run the following command to list recent logs and follow along with any new ones:
|
||
```bash
|
||
# Check Claude's logs for errors
|
||
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
|
||
```
|
||
|
||
**Server not showing up in Claude**
|
||
1. Check your `desktop_config.json` file syntax
|
||
2. Make sure the path to your project is absolute and not relative
|
||
3. Restart Claude for Desktop completely
|
||
|
||
**Tool calls failing silently**
|
||
|
||
If Claude attempts to use the tools but they fail:
|
||
|
||
1. Check Claude's logs for errors
|
||
2. Verify your server builds and runs without errors
|
||
3. Try restarting Claude for Desktop
|
||
</Accordion>
|
||
<Accordion title="Weather API Issues">
|
||
**Error: Failed to retrieve grid point data**
|
||
|
||
This usually means either:
|
||
1. The coordinates are outside the US
|
||
2. The NWS API is having issues
|
||
3. You're being rate limited
|
||
|
||
Fix:
|
||
|
||
- Verify you're using US coordinates
|
||
- Add a small delay between requests
|
||
- Check the NWS API status page
|
||
|
||
**Error: No active alerts for [STATE]**
|
||
|
||
This isn't an error - it just means there are no current weather alerts for that state. Try a different state or check during severe weather.
|
||
</Accordion>
|
||
|
||
</AccordionGroup>
|
||
|
||
<Note>
|
||
For more advanced troubleshooting, check out our guide on [Debugging MCP](/docs/tools/debugging)
|
||
</Note>
|
||
|
||
## Next steps
|
||
|
||
<CardGroup cols={2}>
|
||
<Card
|
||
title="Building a client"
|
||
icon="outlet"
|
||
href="/tutorials/building-a-client"
|
||
>
|
||
Learn how to build your an MCP client that can connect to your server
|
||
</Card>
|
||
<Card
|
||
title="Example servers"
|
||
icon="grid"
|
||
href="/examples"
|
||
>
|
||
Check out our gallery of official MCP servers and implementations
|
||
</Card>
|
||
<Card
|
||
title="Debugging Guide"
|
||
icon="bug"
|
||
href="/docs/tools/debugging">
|
||
Learn how to effectively debug MCP servers and integrations
|
||
</Card>
|
||
<Card
|
||
title="Building MCP with LLMs"
|
||
icon="comments"
|
||
href="/building-mcp-with-llms"
|
||
>
|
||
Learn how to use LLMs like Claude to speed up your MCP development
|
||
</Card>
|
||
</CardGroup> |