Build a Simple MCP Server with Python in Just 10 Minutes

In this article, we are going to build a very basic MCP server using Python. MCP, which stands for Model-Context-Protocol, is a method for giving your language model access to external tools. An MCP server is a back-end system that exposes real-world tools or functions that a language model like GPT, Mistral, or Claude can call during a conversation. It acts as a bridge between a language model and real-world actions.

This guide will walk you through building a basic server from scratch using Python and connecting it to the Claude desktop application. For this demonstration, we'll keep the functionality straightforward: we will build a tool that takes a query, automatically searches it on Google, and opens the results in your default browser.

Prerequisites

Before we begin, ensure you have the following installed: - The Claude desktop app. - UV, a fast, modern Python package manager. UV serves as a drop-in replacement for tools like pip and virtualenv.

We will be following the official MCP Python SDK documentation to set up the server.

Step 1: Project Initialization

First, create a project folder and open it in your preferred code editor, such as Visual Studio Code. Once inside the folder, open a terminal in the current directory.

Run the following command to initialize a new Python project with a virtual environment:

uv init

Step 2: Add Project Dependencies

Next, we need to add the necessary project dependencies. Run this command to add the MCP Python package along with its optional CLI dependencies to your project using UV. This is similar to pip install but also updates your pyproject.toml file with the new dependency.

uv add mcp-server[cli]

This command installs the core MCP library and the extra packages required for command-line support.

Step 3: Implementation

After the installation, you will find a main.py file where you can add your functionality. For this guide, we'll use a modified version of the default template from the MCP documentation.

The code utilizes FastMCP, a class that wraps FastAPI to simplify the process of building MCP servers.

Here is the full code for main.py:

import webbrowser
from urllib.parse import quote_plus
from mcp_server import FastMCP, tool

# This creates an MCP server instance named 'Google Search'.
# This name will appear in your toolset in applications like Claude.
app = FastMCP(
    title="Google Search",
)

@tool(app)
def open_google_search(query: str):
    """
    Searches the given query on Google and opens the results in a new browser tab.
    This description helps the language model understand when and how to use the tool.
    """
    search_url = f"https://www.google.com/search?q={quote_plus(query)}"
    webbrowser.open(search_url)
    return f"Successfully opened Google search for: {query}"

Code Breakdown: - app = FastMCP(title="Google Search"): This line creates an MCP server instance. The title will be displayed in your tool set within Claude. - @tool(app): This decorator informs the MCP server that the following function is a tool a language model can call. - open_google_search(query: str): This is our custom function that takes a user's query as an argument and performs a Google search. It uses the webbrowser and urllib libraries to construct the search URL and open it in the default browser. - The docstring within the function serves as the tool's description, which helps the language model understand its purpose.

Step 4: Adding the Tool to Your Claude Application

To add this new tool to Claude, run the following command in your terminal.

uv mcp install main.py

If you rename main.py to something else, like server.py, you must update the command accordingly (uv mcp install server.py).

After running the command, the tool should automatically be added to your Claude app.

Troubleshooting

Sometimes the tool may not appear immediately. To fix this, open the Claude app and navigate to File > Settings. Click on the Developer tab and then Edit Config. This will open the JSON configuration file for the Claude desktop app.

In the configuration file, you will see a command that uses uv. You need to replace the value "uv" with the absolute path to your uv executable.

To find the absolute path of uv, you can use one of these commands: - On macOS/Linux: which uv - On Windows: where uv

Update the command section in the JSON file with the absolute path. For example:

"command": ["/home/user/.local/bin/uv", "mcp", "run", "main.py"]

Note for Windows users: When adding the path, make sure to use double backslashes (\\), for example: C:\\Users\\YourUser\\...\\uv.exe.

After saving the file, restart the Claude app. You may need to use the Task Manager or Activity Monitor to forcefully stop all Claude instances before restarting.

Once restarted, go back to the Developer tab in the settings. Your tool should now appear with a "running" status.

Step 5: Testing the Tool

Now you can test the tool directly within the Claude app. Try a prompt like:

Search in Google for "what is machine learning"

As you can see, Claude will use our custom MCP tool, and the search results will open in your default browser.

That's it! You have successfully created a basic MCP tool using an MCP server. You can build more complex functionalities on top of this foundation to create a wide variety of powerful tools.