Tutorial: Build a Simple MCP Server With Claude Desktop

In the previous part of this series, I introduced the basic concepts of Model Context Protocol (MCP) — an open standard designed to streamline how AI models interact with external tools, data sources and resources. In this installment, I’ll walk you through the step-by-step process of building an MCP server and integrating it with Claude Desktop.

We’ll use Python and FastMCP 2.0 to build an MCP server that utilizes the FlightAware API. For more information on FlightAware, refer to the previous tutorial, where I integrated it with large language model (LLM) tools. Ensure that you have a valid FlightAware API key before proceeding.

In subsequent parts of this series, I’ll demonstrate how to extend this to work with AI agents built with OpenAI Agents SDK and Google Agent Development Kit (ADK).

Step 1: Setting Up the Environment

Let’s start by creating a virtual environment and installing the required Python modules:

python -m venv venv
source venv/bin/activate

pip install requests fastmcp pytz

Step 2: Building the MCP Server

First, import the required Python modules in the code:

import json
import os 
import requests
import pytz
from datetime import datetime, timedelta
from typing import Any, Callable, Set, Dict, List, Optional
from mcp.server.fastmcp import FastMCP

The next step is to create the MCP object from FastMCP:

mcp = FastMCP("Flight Server")

We’ll then create a function and decorate it with the @mcp.tool() annotation to explicitly identify it as a tool:

@mcp.tool()
def get_flight_status(flight):
 """Returns Flight Information"""
 AEROAPI_BASE_URL = "https://aeroapi.flightaware.com/aeroapi"
 AEROAPI_KEY="YOUR_API_KEY"
 
 def get_api_session():
 session = requests.Session()
 session.headers.update({"x-apikey": AEROAPI_KEY})
 return session
 
 def fetch_flight_data(flight_id, session):
 if "flight_id=" in flight_id:
 flight_id = flight_id.split("flight_id=")[1] 
 
 start_date = datetime.now().date().strftime('%Y-%m-%d')
 end_date = (datetime.now().date() + timedelta(days=1)).strftime('%Y-%m-%d')
 api_resource = f"/flights/{flight_id}?start={start_date}&end={end_date}" # Fixed & to &
 
 try:
 response = session.get(f"{AEROAPI_BASE_URL}{api_resource}")
 response.raise_for_status()
 json_data = response.json()
 
 # Print the response for debugging
 print("API Response:", json.dumps(json_data, indent=2))
 
 if 'flights' not in json_data or len(json_data['flights']) == 0:
 return None
 
 return json_data['flights'][0]
 except Exception as e:
 print(f"Error fetching flight data: {e}")
 return None
 
 def utc_to_local(utc_date_str, local_timezone_str):
 utc_datetime = datetime.strptime(utc_date_str, '%Y-%m-%dT%H:%M:%SZ').replace(tzinfo=pytz.utc)
 local_timezone = pytz.timezone(local_timezone_str)
 local_datetime = utc_datetime.astimezone(local_timezone)
 return local_datetime.strftime('%Y-%m-%d %H:%M:%S') 
 
 session = get_api_session()
 flight_data = fetch_flight_data(flight, session)
 
 if flight_data is None:
 return json.dumps({
 'error': 'Failed to retrieve flight data. Check the API key and flight ID.',
 'flight': flight
 })
 
 try:
 dep_key = 'estimated_out' if 'estimated_out' in flight_data and flight_data['estimated_out'] else \
 'actual_out' if 'actual_out' in flight_data and flight_data['actual_out'] else \
 'scheduled_out'
 
 arr_key = 'estimated_in' if 'estimated_in' in flight_data and flight_data['estimated_in'] else \
 'actual_in' if 'actual_in' in flight_data and flight_data['actual_in'] else \
 'scheduled_in' 
 
 flight_details = f"""
Flight: {flight}
Source: {flight_data['origin']['city']}
Destination: {flight_data['destination']['city']}
Departure Time: {utc_to_local(flight_data[dep_key], flight_data['origin']['timezone'])}
Arrival Time: {utc_to_local(flight_data[arr_key], flight_data['destination']['timezone'])}
Status: {flight_data['status']}
"""
 return flight_details
 except Exception as e:
 print(f"Error processing flight data: {e}")
 return json.dumps({
 'error': f'Error processing flight data: {str(e)}',
 'flight': flight
 })

The last step is to create the main function to run the server if it’s executed directly:

if __name__ == "__main__": 
 mcp.run()

That’s it! We’re done building our first MCP server. It’s time to put it to the test by integrating it with Claude Desktop.

Step 3: Integrating With Claude Desktop

Ensure you have the latest version of Claude Desktop. Open the Settings menu to access the Developer tab:

👁 Image

Click on the Edit Config button to access the MCP settings file named claude_desktop_config.json.

Open the file in your favorite editor and add the following content:

{
 "mcpServers": {
 "flight": {
 "command": "/Users/janakiramm/Demo/venv/bin/python",
 "args": [
 "/Users/janakiramm/Demo/flight_server.py"
 ]
 }
 }
}

Replace the path with the absolute path to your Python environment and MCP server and save the file.

Restart Claude, and you should now find your MCP server within the settings option.

👁 Image

Make sure it’s turned on. Now we’re all set to use our MCP server from Claude.

It’s time to test the MCP server by asking Claude about a flight schedule. Claude will ask for your permission to access a third-party service.

👁 Image

Once you allow it, Claude will invoke the MCP server and fetch the data, which acts as the context to the original prompt.

👁 Image

As we can see from the output, Claude invoked the MCP server to fetch the real-time status. Note that we are using the STDIO transport.

You can find the entire code in the Gist below:

In upcoming articles in this series, we’ll explore how to use other transport protocols, including streamable HTTP transport. Stay tuned!