Créer un serveur MCP en Python avec le SDK officiel

Pour créer un serveur MCP (Model Context Protocol) en Python, la documentation officielle passe par le SDK (kit de développement) Python, installé avec uv, et par la classe MCPServer : vous décorez une fonction avec @mcp.tool(), ses annotations de type et sa docstring deviennent la définition de l'outil, puis mcp.run(transport="stdio") lance le serveur. Voici le chemin, tel que décrit dans le tutoriel officiel relevé le 15/11/2026.

Prérequis

• Python 3.10 ou plus.
• Le SDK Python MCP en version 2.0.0 ou plus (le tutoriel l'exige explicitement).
• uv, le gestionnaire de projets Python utilisé par le tutoriel.

Le SDK Python est l'un des six SDK classés au premier niveau de maturité par le projet MCP, avec TypeScript, C#, Go, Rust et Ruby. Son dépôt est modelcontextprotocol/python-sdk sur GitHub.

Préparer le projet

Sur macOS ou Linux, le tutoriel enchaîne :

uv init weather
cd weather
uv venv
source .venv/bin/activate
uv add "mcp[cli]"
touch weather.py

Sous Windows, l'activation se fait avec .venv\Scripts\activate et la création du fichier avec new-item weather.py. Redémarrez votre terminal après l'installation de uv pour que la commande soit reconnue.

Le serveur minimal

Le tutoriel construit un serveur météo à deux outils. En gardant exactement sa structure, un serveur réduit à un seul outil ressemble à ceci :

from mcp.server import MCPServer

mcp = MCPServer("demo")

@mcp.tool()
async def saluer(nom: str) -> str:
    """Renvoie une salutation.

    Args:
        nom: Prénom de la personne
    """
    return f"Bonjour {nom}"

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

Trois choses à retenir :

1. Le nom passé à MCPServer identifie votre serveur.
2. La signature et la docstring comptent : la documentation précise que MCPServer s'appuie sur les annotations de type et les docstrings pour générer automatiquement la définition des outils. Une description claire aide le modèle à choisir le bon outil au bon moment.
3. transport="stdio" : le serveur dialogue par l'entrée et la sortie standard, ce qui convient quand l'application d'IA le lance elle-même sur votre poste.

Pour lancer le serveur à la main : uv run weather.py (ou le nom de votre fichier).

Le piège de la sortie standard

C'est l'erreur la plus fréquente. En stdio, la sortie standard transporte les messages JSON-RPC du protocole (un format d'appel à distance écrit en JSON). La documentation est formelle : n'écrivez jamais sur stdout, et gardez print() hors d'un serveur stdio. Utilisez le module logging, qui écrit sur stderr :

import logging

logger = logging.getLogger(__name__)
logger.info("Traitement de la requête")  # écrit sur stderr

Pour un serveur HTTP (accessible par le réseau, comme une page web), en revanche, écrire sur la sortie standard ne gêne pas les réponses.

Appels réseau

Le tutoriel utilise httpx2 pour interroger l'API (interface de programmation) du service météo américain, le National Weather Service. Il précise que c'est le client HTTP dont dépend le SDK lui-même : installer mcp l'a déjà installé. Dans vos outils, gérez les erreurs réseau et renvoyez un message lisible plutôt qu'une exception brute : le modèle peut s'en servir pour réessayer autrement.

Brancher le serveur à Claude Desktop

Ouvrez claude_desktop_config.json (sur macOS : ~/Library/Application Support/Claude/claude_desktop_config.json) et ajoutez votre serveur sous la clé mcpServers :

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",
        "run",
        "weather.py"
      ]
    }
  }
}

Deux précautions données par la documentation : le chemin doit être absolu, et il peut être nécessaire de mettre le chemin complet de l'exécutable uv dans command (obtenu avec which uv sur macOS et Linux, where uv sous Windows). Sous Windows, doublez les barres obliques inverses dans le JSON. Enregistrez, puis redémarrez Claude Desktop. Le détail de l'installation et du dépannage est sur la page installer un serveur MCP dans Claude Desktop.

Avant d'aller plus loin

• Testez votre serveur hors de Claude avec MCP Inspector : vous voyez la liste des outils et les échanges JSON-RPC.
• Décidez ce qui doit être un outil, une ressource ou un prompt : voir outils, ressources et prompts.
• Si le serveur touche à des données sensibles, lisez la page sécurité des serveurs MCP avant de le partager.

Vous préférez TypeScript ? Le même serveur est décrit sur la page créer un serveur MCP en TypeScript.