Przejdź do głównej treści
Polski— Wybierz język
Menu

Konfiguracja lokalnego serwera MCP (STDIO)

Lekcja 4 z 14 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Twój pierwszy lokalny serwer MCP
  2. Pisanie serwera
  3. Konfiguracja klienta STDIO
  4. Testuj przed integracją
  5. Kluczowe wnioski

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): MCPServer zastępuje FastMCP, ustawienia transportu przeniesiono do run() lub streamable_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 pakiet mistralai[agents] wymaga mcp>=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
  • StdioServerParameters konfiguruje 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=None dziedziczy całe środowisko; jawny słownik ogranicza dostępne zmienne