MCP Server Python Quickstart: Build Your First Server in 10 Minutes

You can build a fully working MCP server in Python in under 10 minutes using the official MCP Python SDK. This quickstart walks you through every step: installing the SDK, creating a minimal server with a single tool, testing it with the MCP Inspector, and connecting it to Claude Desktop. Every code snippet is copy-paste ready.

This is the fast path. If you want a comprehensive tutorial with detailed explanations, error handling patterns, and advanced features, read our full How to Build an MCP Server in Python pillar guide. This quickstart gets you to a working server as quickly as possible.

Prerequisites

You need two things installed:

If you do not have uv installed, install it with this one-liner:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows, use:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 1: Create the Project

Open your terminal and run these commands to create a new project directory with the MCP SDK installed:

uv init mcp-quickstart
cd mcp-quickstart
uv add "mcp[cli]"

This creates a new Python project, sets up a virtual environment automatically, and installs the MCP Python SDK with its command-line tools.

Step 2: Write the Server

Create a file called server.py in your project directory with the following content:

from mcp.server.fastmcp import FastMCP

# Create the MCP server
mcp = FastMCP("quickstart")


@mcp.tool()
def greet(name: str) -> str:
    """Greet someone by name.

    Args:
        name: The name of the person to greet.
    """
    return f"Hello, {name}! Welcome to MCP."


@mcp.tool()
def add_numbers(a: float, b: float) -> float:
    """Add two numbers together.

    Args:
        a: The first number.
        b: The second number.
    """
    return a + b


@mcp.resource("info://quickstart/about")
def about() -> str:
    """Information about this MCP server."""
    return "This is a quickstart MCP server with greeting and math tools."

That is your complete MCP server. Let us break down what each piece does:

• FastMCP("quickstart") creates a new MCP server instance with the name "quickstart."
• @mcp.tool() registers a Python function as an MCP tool that AI assistants can call. The docstring becomes the tool description that helps the AI understand when and how to use it.
• @mcp.resource() registers a data endpoint that clients can read. Resources expose information; tools perform actions.

The type hints on the function parameters (like name: str and a: float) are important. The SDK uses them to generate the JSON Schema that tells clients what arguments each tool accepts.

Step 3: Test with MCP Inspector

The MCP Inspector is a browser-based testing interface that lets you call your tools interactively. Launch it with:

mcp dev server.py

This starts your server and opens the Inspector at http://localhost:5173. You will see a web interface with three tabs: Tools, Resources, and Prompts.

Testing Your Tools

1. Click the Tools tab.
2. You should see greet and add_numbers listed.
3. Click greet, enter a name in the parameter field, and click Run.
4. You should see the greeting response.
5. Click add_numbers, enter two numbers, and click Run.
6. You should see the sum.

Testing Your Resource

1. Click the Resources tab.
2. You should see info://quickstart/about listed.
3. Click it to read the resource content.

If everything works in the Inspector, your server is ready for Claude Desktop.

Step 4: Connect to Claude Desktop

Claude Desktop uses a JSON configuration file to know which MCP servers to load. You need to find the path to your server's Python executable within the virtual environment that uv created.

First, find the full path to your server file and the Python executable:

# Get the full path to your server file
pwd

# Get the path to the Python executable in your virtual environment
uv run which python

Now edit the Claude Desktop configuration file. The file location depends on your operating system:

Open the file (create it if it does not exist) and add your server to the mcpServers section:

{
  "mcpServers": {
    "quickstart": {
      "command": "/FULL/PATH/TO/.venv/bin/python",
      "args": [
        "-m",
        "mcp.server",
        "/FULL/PATH/TO/mcp-quickstart/server.py"
      ]
    }
  }
}

Replace /FULL/PATH/TO/ with the actual paths from the commands above.

Alternatively, you can use uv to run the server directly:

{
  "mcpServers": {
    "quickstart": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/FULL/PATH/TO/mcp-quickstart",
        "mcp",
        "run",
        "server.py"
      ]
    }
  }
}

Step 5: Verify in Claude Desktop

1. Restart Claude Desktop completely (quit and reopen, not just close the window).
2. Start a new conversation.
3. Look for the MCP tools icon (a hammer icon or similar) in the input area. Click it to see your server's tools listed.
4. Ask Claude: "Greet Alice using the greet tool."
5. Claude should call your greet tool and show the response: "Hello, Alice! Welcome to MCP."
6. Ask Claude: "What is 42 plus 17?" and it should use the add_numbers tool.

If you do not see the tools, check the Claude Desktop logs for error messages. The most common issues are incorrect paths in the configuration file and missing dependencies.

Extending Your Server

Now that you have a working server, here are the most useful next steps:

Add a Tool That Calls an External API

Most real MCP servers wrap external APIs. Here is an example that fetches weather data:

import httpx


@mcp.tool()
async def get_weather(city: str) -> str:
    """Get the current weather for a city.

    Args:
        city: The name of the city to get weather for.
    """
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://wttr.in/" + city,
            params={"format": "3"},
        )
        return response.text.strip()

Note the async keyword. The MCP SDK supports both synchronous and asynchronous tool implementations. Use async for any tool that makes network requests to avoid blocking other tools.

You will also need to install httpx:

uv add httpx

Add a Dynamic Resource

Resources can be dynamic -- they can accept parameters in the URI:

@mcp.resource("file://quickstart/notes/{name}")
def get_note(name: str) -> str:
    """Read a note by name.

    Args:
        name: The name of the note to read.
    """
    notes_dir = "/path/to/your/notes"
    file_path = f"{notes_dir}/{name}.txt"
    with open(file_path, "r") as f:
        return f.read()

Add a Prompt Template

Prompt templates help the AI use your tools effectively:

@mcp.prompt()
def analyze_data(data_description: str) -> str:
    """Create a prompt for data analysis.

    Args:
        data_description: What data to analyze.
    """
    return f"""Please analyze the following data: {data_description}

Use the available tools to:
1. Fetch any needed information
2. Perform calculations
3. Summarize your findings"""

Common Issues and Fixes

What You Have Built

In under 10 minutes, you have:

1. Created a Python MCP server project with proper dependency management
2. Defined tools with type-safe parameters and descriptive docstrings
3. Added a resource endpoint for exposing data
4. Tested everything interactively with the MCP Inspector
5. Connected the server to Claude Desktop

From here, the possibilities are endless. You can build servers that connect to databases, interact with APIs, automate file operations, or integrate with any service that has a Python library.

What to Read Next

• How to Build an MCP Server in Python -- the comprehensive tutorial with advanced patterns and error handling
• Adding Authentication to Python MCP Servers -- secure your server with API keys and OAuth
• Testing and Debugging MCP Servers -- systematic approaches to testing your tools
• MCP Building Blocks -- understand tools, resources, and prompts in depth
• Browse Example Servers -- see how production MCP servers are built