Turn your server into a professional Python package—installable, distributable, and ready to publish.
Having an MCP Server running as a script is great for development, but to distribute, version, and let others use your work, you need to turn it into a professional Python package. Packaging means creating a structure that lets you install with pip or uv, declare dependencies, define versions, and share reliably with the community.
Package your MCP Server means turning it from a loose script into a Python project with a formal structure: metadata declared in the pyproject.toml, explicit dependencies, semantic versioning, and an entry point that lets you run the server with a single command in the terminal. You can install a package with pip install or uv pip install, distributed via PyPI or GitHub, and versioned with Git tags. The difference between a standalone script and a professional package is the difference between a prototype and a product.
uv pip install .
Think of packaging as putting your server in a professional toolbox with an instruction manual. Without the box, you have loose parts that only you know how to assemble. With the box, anyone can install and use it with a single command. Start with uv init to create the basic structure automatically.
O pyproject.toml is the central file for any modern Python project. It replaces the old setup.py e setup.cfg with a clean declarative syntax standardized by PEP 621. This is where you define the package name, version, description, dependencies, and how the package should be built.
A pyproject.toml typical for an MCP Server:
[project] name = "meu-mcp-server" version = "0.1.0" description = "MCP Server para consulta de dados" requires-python = ">=3.10" dependencies = [ "fastmcp>=0.1.0", "httpx>=0.25", ] [build-system] requires = ["hatchling"] build-backend = "hatchling.build" [project.scripts] meu-server = "meu_server.server:main"
The section [project] defines metadata, [build-system] defines how to build and [project.scripts] creates executable commands in the terminal.
Use hatchling as a build backend — it's modern, fast, and works perfectly with uv. If you prefer, setuptools also works, but hatchling is the recommended choice for new projects. Never write a setup.py — o pyproject.toml is the official standard since PEP 621.
PEP 621 (2021) standardized Python project metadata in pyproject.toml. Since then, more than 85% of new packages published on PyPI adopted this format. The setup.py is considered legacy—it works, but isn’t recommended for new projects. Modern tools like uv, hatch e rye work natively with pyproject.toml.
A Python package’s directory structure follows conventions that make building, testing, and distribution easier. The pattern src layout is the recommended approach for avoiding import issues and ensuring that tests run against the installed package, not the local source code.
Recommended structure for a packaged MCP Server:
meu-mcp-server/ ├── pyproject.toml ├── README.md ├── src/ │ └── meu_server/ │ ├── __init__.py │ └── server.py └── tests/ └── test_server.py
The directory src/ isolates the source code. The __init__.py marks the directory as a Python package. The server.py contains the MCP Server logic with the function main().
Create the project's root directory and initialize it with uv init meu-mcp-server.
Create src/meu_server/ with __init__.py and move the server code to server.py.
Create directory tests/ and configure the pyproject.toml with metadata, dependencies, and entry points.
Entry points are the magic that lets you turn your MCP Server into a executable command in the terminal. Instead of running python -m meu_server.server, the user simply types meu-server and the package is run. This is configured in the [project.scripts] of the pyproject.toml.
The entry point configuration in pyproject.toml:
[project.scripts] meu-server = "meu_server.server:main"
This tells Python: "when someone types meu-server in the terminal, run the function main() from the file server.py inside the package meu_server." After installation, the command is available globally in the active virtual environment.
Make sure your function main() in server.py calls mcp.run(). This is the function that will be invoked when the user runs the command in the terminal. Always test with uv pip install -e . (editable mode) during development — this way, code changes are reflected immediately without reinstalling.
The command name (before the =) uses hyphens: meu-server. The module path (after the =) uses underscores: meu_server.server:main. Mixing the two is a common mistake that results in ModuleNotFoundError. Remember: hyphens in the terminal, underscores in Python.
Declaring dependencies correctly is essential for your package to work on any machine. In pyproject.toml, you list all the libraries your server needs with version constraints that ensure compatibility without blocking updates. The uv lock generates a lockfile that pins exact versions for reproducibility.
Dependencies are declared in the section [project] with semantic versioning (semver):
dependencies = [
"fastmcp>=0.1.0", # mínimo 0.1.0
"httpx>=0.25,<1.0", # entre 0.25 e 1.0
"pydantic>=2.0", # mínimo 2.0
]
Semver (semantic versioning) uses the format MAJOR.MINOR.PATCH: MAJOR changes when there are breaking changes, MINOR for new features, PATCH for bug fixes. Use >= for minimums and < for compatibility caps.
fastmcp==0.1.0httpxuv lock to generate a lockfile>=0.1.0,<1.0uv lock and commit the uv.lock
According to PyPI analyses, 23% of problems of Python package installation are caused by poorly specified dependencies — incompatible versions, missing dependencies, or overly strict constraints. Using lockfiles (uv.lock) reduces reproducibility failures by more than 90%, ensuring that all developers and production environments use exactly the same versions.
Before distributing your package, you need to verify that it works when installed — not only when run directly from the source code. This means building the package with uv build, install the file .whl generated and test that the entry point works correctly.
The build process generates distributable files in the folder dist/:
# Construir o pacote $ uv build Successfully built meu_server-0.1.0-py3-none-any.whl # Instalar o .whl gerado $ uv pip install dist/meu_server-0.1.0-py3-none-any.whl # Testar o entry point $ meu-server MCP Server rodando...
The file .whl (wheel) is the standard Python distribution format. It contains your code, metadata, and entry point information — everything pip/uv needs to install correctly.
Run uv build and verify that the .whl is generated without errors in the folder dist/.
Create a clean virtual environment and install the .whl with uv pip install — simulates a real installation.
Run the entry point command and verify that the server starts correctly and responds to MCP requests.
Always test in a clean virtual environment — not in the same environment where you developed it. This ensures all dependencies are correctly declared in the pyproject.toml. If something works in your dev environment but fails in a clean one, it means you forgot to declare a dependency.
Next Module: 5.2 — Publishing on GitHub