Конфигуриране на локален MCP сървър (STDIO)
На тази страница
Обновено на 2 ноември 2026 г. — MCP Python SDK v2. Този курс следва версия 2 на
mcpSDK (2.3.0 към 2 октомври 2026 г.):MCPServerзаместваFastMCP, настройките за транспорт се преместват вrun()илиstreamable_http_app(), а приложението, изложено под реално име на хост, трябва да декларира това име (transport_security). Това е също версията, изисквана от Mistral SDK: допълнениетоmistralai[agents]изискваmcp>=2.2.0,<3.0. Източници: Какво е ново във v2 · Ръководство за миграция · Разполагане и мащабиране.
Вашият първи локален MCP сървър
Режимът STDIO е естествената отправна точка за разработване и тестване на MCP сървър: всичко работи на Вашата машина, без разполагане, без публичен URL и без сертификати за управление. Вие редактирате файл, рестартирате и наблюдавате. В този урок ще напишете локален MCP сървър на Python и след това ще го свържете с клиент.
Що се отнася до предварителните изисквания, имате нужда от Python 3.10 или по-нова версия, актуален pip и за предпочитане отделна виртуална среда. Последното не е козметично: MCP пакетите еволюират бързо и отделна виртуална среда за всеки проект Ви предпазва от нарушаване на работещ сървър при инсталиране на зависимост за друг.
# Създаване на виртуална среда
python -m venv mcp-env
source mcp-env/bin/activate # Linux/Mac
# mcp-env\Scripts\activate # Windows
# Официален MCP SDK (v2) и Mistral SDK с неговото допълнение за агенти
pip install "mcp[cli]>=2.2,<3" "mistralai[agents]"
Написване на сървъра
С MCPServer, класът от високо ниво в официалния SDK (предишно FastMCP), локалният сървър изисква само няколко реда. Вие инстанцирате приложение, като му дадете описателно име, след което декорирате Вашите Python функции с @app.tool(), за да ги изложите.
# serveur_local.py
from mcp.server.mcpserver import MCPServer
# Инициализиране на сървъра с описателно име
app = MCPServer("Local Demo Server")
@app.tool()
def greet(name: str) -> str:
"""Поздравява човек по име.
Args:
name: Името на човека, който да бъде поздравен
Returns:
Персонализирано поздравително съобщение
"""
return f"Hello {name}! Welcome to the world of MCP."
@app.tool()
def calculate(operation: str, a: float, b: float) -> str:
"""Извършва проста математическа операция.
Args:
operation: Операцията за изпълнение (add, sub, mul, div)
a: Първо число
b: Второ число
Returns:
Резултатът от изчислението
"""
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}"
Този файл излага два инструмента. Обърнете внимание на ролята на docstrings: те не просто документират кода Ви за колега; те буквално стават описанието, което моделът чете, за да реши дали да извика calculate вместо greet. Небрежен docstring тук води до erratic извиквания по-късно.
Конфигуриране на STDIO клиента
От страна на клиента, Вие не се свързвате с адрес; Вие обяснявате как да стартирате сървъра. Това е ролята на StdioServerParameters.
# client_stdio.py
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
from pathlib import Path
# Път до Вашия сървър
path_to_server = Path("serveur_local.py")
# Конфигурация на STDIO сървъра
server_params = StdioServerParameters(
command="python", # Командата за стартиране на сървъра
args=[str(path_to_server)], # Аргументите (Python файлът)
env=None, # Променливи на средата (по избор)
)
# Създаване на MCP клиента
mcp_client = MCPClientSTDIO(stdio_params=server_params)
Три параметъра заслужават детайли.
command
Това е системната команда, която стартира процеса на сървъра: "python" за Python сървър, "node" за JavaScript сървър или директният път до двоичен файл, ако сървърът Ви е компилиран.
# Python
command="python"
# Node.js
command="node"
# Компилиран изпълним файл
command="./mon_serveur_mcp"
args
Това е списъкът с аргументи, предадени на тази команда. За Python скрипт това е поне пътят до файла, но нищо не Ви пречи да предадете опциите на Вашия сървър тук.
# Обикновен скрипт
args=["serveur_local.py"]
# С допълнителни аргументи
args=["serveur_local.py", "--port", "8080", "--verbose"]
env
Това е речникът с променливи на средата, предадени на процеса на сървъра: каналът, чрез който му предавате API ключ, URL на база данни или флаг за дебъгване.
import os
server_params = StdioServerParameters(
command="python",
args=["serveur_local.py"],
env={
**os.environ, # Наследяване от текущата среда
"API_KEY": "your_api_key",
"DATABASE_URL": "postgresql://...",
"DEBUG": "true",
},
)
Поведението на този параметър често изненадва хората. С env=None, сървърът наследява цялата среда на родителския процес; с речник, той вижда строго само изброените променливи. Ако предоставите речник, без да изхвърлите os.environ в него, не се изненадвайте, ако сървърът Ви вече не може да намери своя PATH или Вашия API ключ: поведението е напълно логично, просто радикално.
Тестване преди интегриране
Преди да включите сървъра си в агент, тествайте го изолирано с MCP Inspector. Логиката е проста: ако извикване се провали, след като сървърът е свързан с модел, няма да знаете дали проблемът е във Вашия код или в решението на модела. Inspector премахва тази двусмисленост.
npx @modelcontextprotocol/inspector python serveur_local.py
Командата отваря локален уеб интерфейс, където можете да изброите изложените инструменти, да инспектирате описанието и параметрите, които моделът ще получи, да задействате ръчно извикване с аргументи по Ваш избор и да проверите точния формат на върнатата стойност. Направете си навик да използвате това систематично: това са пет минути, които спестяват един час.
Накрая, ето организация на файлове, която остарява добре, със сървъра, клиента, зависимостите, тайните, държани извън хранилището, и модулни тестове за Вашите инструменти:
mon-projet-mcp/
├── serveur_local.py # MCP сървърът
├── client_stdio.py # Скриптът на клиента
├── requirements.txt # Зависимости
├── .env # Променливи на средата (никога не се комитват)
└── tests/
└── test_tools.py # Модулни тестове за инструменти
Ключови изводи
- STDIO сървърът се стартира като локален процес
StdioServerParametersконфигурира командата, аргументите и променливите на средата- Docstrings на Вашите инструменти служат като описание за модела
- MCP Inspector (
npx @modelcontextprotocol/inspector) е съществен за тестване env=Noneнаследява цялата среда; изричен речник ограничава променливите