link_to_page

Pre-assumption

This guide assumes that readers are familiar with Linux or MacOS command line interface (CLI) and what is a MCP server.

Brief introduction

This guide shows how to build a MCP server from scratch. This note is composed by three parts: UV introduction, Code development, and deployment.

UV introduction

UV is a rust based Python package and project manager. There are no differences between UV and other managers except UV is very fast. Also, MCP uses UVX, a UV tool for running python package, to run the server. So in this note, we’ll use UV to manage our project.

Installation

UV now can use PyPi for installation:

1

pip install uv

Change the source [optional]

Sometimes we need to change the source of UV because of the special network environment. Please consider add the following command to your environment.

1

export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

This command changes the source of UV from the official site to TUNA temporarily. If you want to persist your modification, please refer doc from tuna.

Python setup

For convenience, we use UV to setup our python interpreter.

1

uv python install

Then, we use the following command to setup a python project in a directory.

1
2
3
4

mkdir note # build a new directory for our code
uv init ./note # setup the direcory as our workspace
cd note # get into the workspace
uv venv # starts a new virtual environment

If success, there will be some new files generated by UV and the directory should be like this:

Summary

We have installed the UV, set up a interpreter, and initialized a new workspace for our project. In the next step, we’ll go through the project and implement a very simple MCP server.

Code development

In this section, we’ll start implementing a very simple MCP server. We’ll start with going through our workspace, install some dependencies, implement some code, and debug the code.

Workspace go through

We can see our project structure in here. There are some files in this workspace which is generated by UV. But do not worry about it. We only need to take care about three files: main.py, README.md, and pyproject.toml.

• The main.py file is the place where the code will be executed and is the place we’ll focus on in this section.
• The README.md is the place you might want to write something.
• The pyproject.toml is the file we manage our project when packaging, which will be introduced later.

Dependencies installation

In this project, we mainly use FastMCP for developing our server. You can find information about the python package here. In a short, FastMCP is a simple yet very useful tool for us to implement MCP servers using python. The installation command using UV is demonstrated as below.

1

uv pip install fastmcp

Implement code

After we have installed the FastMCP, we then can implement our code like the following.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

from fastmcp import FastMCP  # Import the FastMCP class from the fastmcp module

# Create a FastMCP server instance with the name "note"
server = FastMCP("note")

# Register a tool/endpoint named "hello_world" using the @server.tool() decorator
@server.tool()
def hello_world():
    return "Hello World"  # The function returns "Hello World" when called

def main():
    server.run()

# Standard Python idiom to check if the script is being run directly
if __name__ == "__main__":
    main()  # Start the FastMCP server

How to run the code

In our terminal, we can run our code by using fastmcp commands.

1
2
3

# in our project directory
source .venv/bin/activate #activate the virtual environment we built
fastmcp dev main.py # run the code in development code

if it goes well, you’ll see some information in your terminal.

The information is telling you that the inspector server is running in port 6274 and you can access to the inspector server using the URL link it provides. The inspector server is a tool for us to verify our code. We’ll not spend too much time to introduce.

You’ll see the screen once you access to the inspector server. And click the connect button on the left side.

After connection is established, your screen will be like this.

We’ll first click Tools button and choose List Tools to check the tools we implement. And run the tool.

If the tool is executed successfully, you’ll see the result in the following screen. Then you have successfully run a mcp tool.

Debug the code

I, personally, recommend to use various of tests like UT, AT, or regression tests to test your code locally. Because it is much more convenient for us to use.

Some suggestions:

1. Write detailed comment for the tool we implement, it’ll help LLM to understand the function it can use.
2. Add type expectations to your function inputs and outputs. It’ll avoid some mistakes from input side.

Summary

In this section, we have gone through our project, implemented some code, and run it using MCP inspector.

Package deployment

In this section, we can deploy our mcp server for LLM to use. We’ll need to update the pyproject.toml we mentioned before to package our code.

update executable information

In our project, we add the following lines to our pyproject.toml:

1
2

[project.scripts]
note = "main:main"  # Executes the `main()` function in `main.py`

Add dependencies information

we need to include dependencies in our package, we can use the following command to add the package we use to the pyproject.toml

1

uv add fastmcp

Of course it looks uncomfortable if we have many packages we need to depend. We also can use other tools to do this.

deploy your code

we use the following commands packaging our code and run it.

1
2
3

uv build --wheel # packaging your code into wheel
uv install ${PATHTOYOURPACKAGE} # install the packaged code
uvx --python=$(which python) ${PACKAGE} # run the package using specific python interpreter

If all goes well, you’ll see the following information in the CLI. It tells you that your MCP server is running.