Konfiguracja lokalnego serwera MCP (STDIO)
Na tej stronie
Zaktualizowano 2 listopada 2026 — MCP Python SDK v2. Ten kurs opiera się na wersji 2 SDK
mcp(2.3.0 na dzień 2 października 2026):MCPServerzastępujeFastMCP, ustawienia transportu przeniesiono dorun()lubstreamable_http_app(), a aplikacja udostępniana pod rzeczywistą nazwą hosta musi ją jawnie zadeklarować (transport_security). Jest to również wersja wymagana przez Mistral SDK: dodatkowy pakietmistralai[agents]wymagamcp>=2.2.0,<3.0. Źródła: Co nowego w v2 · Przewodnik migracyjny · Wdrażanie i skalowanie.
Twój pierwszy lokalny serwer MCP
Tryb STDIO to naturalny punkt wyjścia do tworzenia i testowania serwera MCP: wszystko działa na Twojej maszynie, bez wdrażania, publicznego adresu URL czy zarządzania certyfikatami. Edytujesz plik, restartujesz proces i obserwujesz wyniki. W tej lekcji napiszesz lokalny serwer MCP w Pythonie, a następnie podłączysz go do klienta.
Jeśli chodzi o wymagania wstępne, potrzebujesz Pythona 3.10 lub nowszego, aktualnego menedżera pip oraz najlepiej dedykowanego środowiska wirtualnego. Ta ostatnia kwestia nie jest tylko formalnością: pakiety MCP ewoluują szybko, a oddzielne środowisko wirtualne (venv) dla każdego projektu zapobiegnie uszkodzeniu działającego serwera podczas instalowania zależności dla innego.
# Utwórz środowisko wirtualne
python -m venv mcp-env
source mcp-env/bin/activate # Linux/Mac
# mcp-env\Scripts\activate # Windows
# Oficjalne SDK MCP (v2) oraz Mistral SDK z dodatkiem agents
pip install "mcp[cli]>=2.2,<3" "mistralai[agents]"
Pisanie serwera
Dzięki klasie wysokiego poziomu MCPServer z oficjalnego SDK (dawniej FastMCP), stworzenie lokalnego serwera zajmuje zaledwie kilka linii. Instancjonujesz aplikację, nadając jej opisową nazwę, a następnie dekorujesz swoje funkcje Pythona za pomocą @app.tool(), aby je udostępnić.
# serveur_local.py
from mcp.server.mcpserver import MCPServer
# Inicjalizacja serwera z opisową nazwą
app = MCPServer("Local Demo Server")
@app.tool()
def greet(name: str) -> str:
"""Greets a person by name.
Args:
name: The first name of the person to greet
Returns:
A personalized greeting message
"""
return f"Hello {name}! Welcome to the world of MCP."
@app.tool()
def calculate(operation: str, a: float, b: float) -> str:
"""Performs a simple mathematical calculation.
Args:
operation: The operation to perform (add, sub, mul, div)
a: First number
b: Second number
Returns:
The result of the calculation
"""
ops = {
"add": a + b,
"sub": a - b,
"mul": a * b,
"div": a / b if b != 0 else "Error: division by zero"
}
result = ops.get(operation, "Unknown operation")
return f"{a} {operation} {b} = {result}"
Ten plik udostępnia dwa narzędzia. Zwróć uwagę na rolę docstringów: nie służą one tylko dokumentowaniu kodu dla współpracownika; dosłownie stają się opisem, który model odczytuje, aby zdecydować, czy wywołać calculate, czy greet. Niedbały docstring prowadzi później do chaotycznych wywołań.
Konfiguracja klienta STDIO
Po stronie klienta nie łączysz się z adresem; wyjaśniasz, jak uruchomić serwer. Do tego służy StdioServerParameters.
# client_stdio.py
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
from pathlib import Path
# Ścieżka do Twojego serwera
path_to_server = Path("serveur_local.py")
# Konfiguracja serwera STDIO
server_params = StdioServerParameters(
command="python", # Polecenie uruchamiające serwer
args=[str(path_to_server)], # Argumenty (plik Pythona)
env=None, # Zmienne środowiskowe (opcjonalne)
)
# Utwórz klienta MCP
mcp_client = MCPClientSTDIO(stdio_params=server_params)
Trzy parametry wymagają szczegółowego omówienia.
command
To polecenie systemowe, które uruchamia proces serwera: "python" dla serwera w Pythonie, "node" dla serwera w JavaScript lub bezpośrednia ścieżka do pliku binarnego, jeśli serwer jest skompilowany.
# Python
command="python"
# Node.js
command="node"
# Skompilowany plik wykonywalny
command="./mon_serveur_mcp"
args
To lista argumentów przekazywanych do tego polecenia. W przypadku skryptu Pythona jest to co najmniej ścieżka do pliku, ale nic nie stoi na przeszkodzie, aby przekazać tutaj opcje konfiguracji serwera.
# Prosty skrypt
args=["serveur_local.py"]
# Z dodatkowymi argumentami
args=["serveur_local.py", "--port", "8080", "--verbose"]
env
To słownik zmiennych środowiskowych przekazywanych do procesu serwera: kanał, przez który przekażesz mu klucz API, adres URL bazy danych lub flagę debugowania.
import os
server_params = StdioServerParameters(
command="python",
args=["serveur_local.py"],
env={
**os.environ, # Dziedziczenie z bieżącego środowiska
"API_KEY": "your_api_key",
"DATABASE_URL": "postgresql://...",
"DEBUG": "true",
},
)
Zachowanie tego parametru często zaskakuje. Przy env=None serwer dziedziczy całe środowisko procesu nadrzędnego; przy podaniu słownika widzi wyłącznie wymienione zmienne. Jeśli przekażesz słownik bez uwzględnienia os.environ, nie dziwiąc się, że serwer nie może znaleźć zmiennej PATH lub Twojego klucza API: zachowanie jest całkowicie logiczne, po prostu radykalne.
Testuj przed integracją
Zanim podłączysz serwer do agenta, przetestuj go w izolacji za pomocą MCP Inspector. Logika jest prosta: jeśli wywołanie nie powiedzie się po podłączeniu serwera do modelu, nie będziesz wiedzieć, czy problem leży w Twoim kodzie, czy w decyzji modelu. Inspector usuwa tę niejednoznaczność.
npx @modelcontextprotocol/inspector python serveur_local.py
Polecenie otwiera lokalny interfejs webowy, w którym możesz wyświetlić listę udostępnionych narzędzi, sprawdzić opis i parametry, które otrzyma model, ręcznie wywołać narzędzie z wybranymi argumentami oraz zweryfikować dokładny format zwracanej wartości. Wyrób sobie nawyk systematycznego korzystania z tego narzędzia: to pięć minut, które oszczędza godzinę pracy.
Na koniec oto struktura projektu, która dobrze się starzeje, zawierająca serwer, klienta, zależności, tajemnice trzymane poza repozytorium oraz testy jednostkowe dla narzędzi:
mon-projet-mcp/
├── serveur_local.py # Serwer MCP
├── client_stdio.py # Skrypt klienta
├── requirements.txt # Zależności
├── .env # Zmienne środowiskowe (nigdy nie commituj)
└── tests/
└── test_tools.py # Testy jednostkowe narzędzi
Kluczowe wnioski
- Serwer STDIO uruchamia się jako lokalny proces
StdioServerParameterskonfiguruje polecenie, argumenty i zmienne środowiskowe- Docstringi Twoich narzędzi służą jako opis dla modelu
- MCP Inspector (
npx @modelcontextprotocol/inspector) jest niezbędny do testowania env=Nonedziedziczy całe środowisko; jawny słownik ogranicza dostępne zmienne