Установка и настройка

Правильная настройка окружения — залог быстрой и комфортной разработки MCP серверов. В этой теме установим все необходимые инструменты и подготовимся к разработке.

#1. Требования к окружению

#Минимальные требования

Компонент	Версия	Зачем
Python	3.10+	MCP SDK требует асинхронные возможности
pip/poetry	Любая	Управление зависимостями
Git	2.0+	Контроль версий кода
Текстовый редактор	Любой	VS Code, PyCharm, Neovim

#Рекомендуемые требования

Компонент	Версия	Зачем
Python	3.11+	Улучшенная производительность, лучшие error messages
Poetry	1.7+	Современное управление зависимостями
Docker	24.0+	Для тестирования и деплоя
Claude Desktop	Последняя	Тестирование интеграции с LLM

#2. Установка Python

#macOS

# Через Homebrew (рекомендуется)
brew install python@3.11

# Проверка установки
python3 --version  # Python 3.11.x
pip3 --version     # pip 23.x

#Linux (Ubuntu/Debian)

# Установка Python 3.11
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev

# Проверка
python3.11 --version

#Windows

# Скачайте установщик с python.org
# https://www.python.org/downloads/windows/

# При установке отметьте "Add Python to PATH"

# Проверка в PowerShell
python --version
pip --version

#3. Установка Poetry (рекомендуемый менеджер зависимостей)

#Почему Poetry?

Атомарные обновления — все или ничего
Lock файлы — воспроизводимые сборки
Виртуальные окружения — автоматическая изоляция
Публикация — встроенная поддержка PyPI

#Установка Poetry

# macOS/Linux (официальный скрипт)
curl -sSL https://install.python-poetry.org | python3 -

# Windows (PowerShell)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

# Проверка
poetry --version  # Poetry version 1.7.x

#Настройка Poetry

# Создать виртуальные окружения в папке проекта
poetry config virtualenvs.in-project true

# Показать настройки
poetry config --list

#4. Создание проекта MCP сервера

#Инициализация проекта

# Создайте папку проекта
mkdir my-mcp-server
cd my-mcp-server

# Инициализация Poetry проекта
poetry init

# Ответьте на вопросы:
# Package name: my-mcp-server
# Version: 0.1.0
# Description: My first MCP server
# Author: Your Name <your@email.com>
# License: MIT
# Python version: ^3.11
# Interactive definition: yes

#Добавление зависимостей

# Основной пакет MCP
poetry add mcp

# Дополнительные зависимости для разработки
poetry add --group dev pytest pytest-asyncio black ruff mypy

# Для HTTP сервера (если нужен SSE/WebSocket транспорт)
poetry add fastapi uvicorn sse-starlette

# Для работы с базами данных
poetry add sqlalchemy aiohttp

#Структура проекта

my-mcp-server/
├── pyproject.toml          # Конфигурация Poetry
├── poetry.lock             # Зафиксированные версии зависимостей
├── README.md               # Документация
├── .gitignore              # Игнорируемые файлы
├── src/
│   └── my_mcp_server/
│       ├── __init__.py
│       ├── server.py       # Основной код сервера
│       ├── resources.py    # Resources provider
│       ├── tools.py        # Tools provider
│       └── prompts.py      # Prompts provider
└── tests/
    ├── __init__.py
    └── test_server.py      # Тесты

#5. Установка MCP SDK

#Официальный пакет

# Внутри проекта с Poetry
poetry add mcp

# Или с pip
pip install mcp

#Проверка установки

poetry run python -c "import mcp; print(mcp.__version__)"

#Версии и совместимость

MCP SDK	Спецификация	Статус
1.0+	2024-11-05	Актуальная
0.x	2024-05-31	Устаревшая

Важно: Используйте последнюю версию MCP SDK для поддержки актуальной спецификации протокола.

#6. Настройка Claude Desktop для тестирования

#Расположение конфигурации

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

#Добавление MCP сервера в конфиг

{
  "mcpServers": {
    "my-local-server": {
      "command": "poetry",
      "args": ["run", "python", "src/my_mcp_server/server.py"],
      "cwd": "/path/to/my-mcp-server",
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

#Поля конфигурации

Поле	Тип	Обязательное	Описание
`command`	string	Да	Команда для запуска (python, node, etc.)
`args`	array	Нет	Аргументы командной строки
`cwd`	string	Нет	Рабочая директория процесса
`env`	object	Нет	Переменные окружения

#Перезапуск Claude Desktop

После изменения конфига:

Закройте Claude Desktop (Cmd+Q / Ctrl+Q)
Запустите снова
Проверьте подключение в настройках (Settings → MCP)

#7. Отладка MCP серверов

#Логирование в stdout

import logging
import sys

# Настройка логирования
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    stream=sys.stderr  # Логи в stderr, чтобы не мешать JSON-RPC в stdout
)

logger = logging.getLogger(__name__)

Важно: При использовании stdio транспорта, MCP сообщения идут через stdout. Логируйте в stderr, чтобы не ломать протокол.

#Использование MCP Inspector

Официальный инструмент для отладки MCP серверов:

# Установка
npm install -g @modelcontextprotocol/inspector

# Запуск
npx @modelcontextprotocol/inspector python src/my_mcp_server/server.py

# Откройте браузер на http://localhost:5173

Возможности Inspector:

Просмотр доступных ресурсов, инструментов, промптов
Ручной вызов инструментов
Чтение ресурсов
Просмотр JSON-RPC сообщений

#Отладка с VS Code

Создайте .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "MCP Server: Debug",
      "type": "debugpy",
      "request": "launch",
      "module": "my_mcp_server.server",
      "console": "integratedTerminal",
      "env": {
        "DEBUG": "true"
      }
    }
  ]
}

#8. Переменные окружения

#Безопасное хранение секретов

❌ ПЛОХО: Секреты в коде

API_KEY = "sk-1234567890abcdef"  # Никогда так не делайте!

✅ ХОРОШО: Переменные окружения

import os
from dotenv import load_dotenv

load_dotenv()  # Загрузка из .env файла

API_KEY = os.getenv("API_KEY")
if not API_KEY:
    raise ValueError("API_KEY not set")

#Создание .env файла

# .env (добавьте в .gitignore!)
API_KEY=your-secret-key
DATABASE_URL=postgresql://user:pass@localhost/db
DEBUG=true

#.env.example для команды

# .env.example (можно коммитить в git)
API_KEY=your-api-key-here
DATABASE_URL=postgresql://user:pass@localhost/dbname
DEBUG=false

#9. Подготовка к разработке: чеклист

Python 3.11+ установлен и в PATH
Poetry установлен (poetry --version)
Проект инициализирован (poetry init)
MCP SDK установлен (poetry add mcp)
Структура папок создана
Claude Desktop настроен (конфиг обновлён)
Логирование настроено (stderr)
.env файл создан (в .gitignore)
Git репозиторий инициализирован

#10. Первый запуск: проверка окружения

#Тестовый скрипт

Создайте test_setup.py:

#!/usr/bin/env python3
"""Проверка правильности настройки окружения для MCP разработки."""

import sys
import logging

def check_python_version():
    """Проверка версии Python."""
    version = sys.version_info
    print(f"Python version: {version.major}.{version.minor}.{version.micro}")
    if version.major < 3 or (version.major == 3 and version.minor < 10):
        print("❌ Python 3.10+ required!")
        return False
    print("✅ Python version OK")
    return True

def check_mcp_installed():
    """Проверка установки MCP SDK."""
    try:
        import mcp
        print(f"MCP version: {mcp.__version__}")
        print("✅ MCP SDK installed")
        return True
    except ImportError:
        print("❌ MCP SDK not installed!")
        print("   Run: poetry add mcp")
        return False

def check_logging():
    """Проверка настройки логирования."""
    logging.basicConfig(
        level=logging.DEBUG,
        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
    )
    logger = logging.getLogger(__name__)
    logger.info("Logging test")
    print("✅ Logging configured")
    return True

def main():
    print("=" * 50)
    print("MCP Development Environment Check")
    print("=" * 50)
    
    checks = [
        check_python_version(),
        check_mcp_installed(),
        check_logging()
    ]
    
    print("=" * 50)
    if all(checks):
        print("✅ All checks passed! Ready to develop.")
    else:
        print("❌ Some checks failed. Fix issues above.")
        sys.exit(1)

if __name__ == "__main__":
    main()

#Запуск проверки

poetry run python test_setup.py

Ожидаемый вывод:

==================================================
MCP Development Environment Check
==================================================
Python version: 3.11.7
✅ Python version OK
MCP version: 1.0.0
✅ MCP SDK installed
2026-03-17 10:00:00 - __main__ - INFO - Logging test
✅ Logging configured
==================================================
✅ All checks passed! Ready to develop.

#11. Полезные команды разработки

# Запуск сервера
poetry run python src/my_mcp_server/server.py

# Запуск с отладкой
poetry run python -m pdb src/my_mcp_server/server.py

# Форматирование кода
poetry run black src/ tests/

# Линтинг
poetry run ruff check src/ tests/

# Типизация
poetry run mypy src/

# Тесты
poetry run pytest tests/ -v

# Обновление зависимостей
poetry update

# Экспорт зависимостей
poetry export -f requirements.txt > requirements.txt

#12. Решение распространённых проблем

#Проблема: "ModuleNotFoundError: No module named 'mcp'"

Решение:

# Убедитесь, что используете Poetry окружение
poetry install
poetry run python your_script.py

# Или активируйте окружение
poetry shell
python your_script.py

#Проблема: Claude Desktop не видит сервер

Решение:

Проверьте путь в конфиге (cwd и args)
Убедитесь, что команда запуска работает вручную
Проверьте логи Claude Desktop
Перезапустите Claude Desktop

#Проблема: Логи ломают JSON-RPC сообщения

Решение:

# Логируйте в stderr, не в stdout
logging.basicConfig(stream=sys.stderr)

# Или используйте файл для логов
logging.basicConfig(filename='server.log', level=logging.DEBUG)

#Проблема: Конфликт версий зависимостей

Решение:

# Удалите lock файл и пересоздайте
rm poetry.lock
poetry install

# Или обновите конкретную зависимость
poetry update mcp

#Ключевые выводы

Инструмент	Назначение
Python 3.10+	Требуется для асинхронных возможностей MCP SDK
Poetry	Управление зависимостями и виртуальными окружениями
MCP SDK	Официальная библиотека для создания серверов
Claude Desktop	Тестирование интеграции с LLM
MCP Inspector	Отладка серверов, просмотр запросов
.env	Безопасное хранение секретов

Следующая тема: Первый MCP сервер — создание Hello World сервера с нуля, запуск и тестирование.

Компонент

Версия

Зачем

Python

3.10+

MCP SDK требует асинхронные возможности

pip/poetry

Любая

Управление зависимостями

Git

2.0+

Контроль версий кода

Текстовый редактор

Любой

VS Code, PyCharm, Neovim

Компонент

Версия

Зачем

Python

3.11+

Улучшенная производительность, лучшие error messages

Poetry

1.7+

Современное управление зависимостями

Docker

24.0+

Для тестирования и деплоя

Claude Desktop

Последняя

Тестирование интеграции с LLM

my-mcp-server/ ├── pyproject.toml # Конфигурация Poetry ├── poetry.lock # Зафиксированные версии зависимостей ├── README.md # Документация ├── .gitignore # Игнорируемые файлы ├── src/ │ └── my_mcp_server/ │ ├── __init__.py │ ├── server.py # Основной код сервера │ ├── resources.py # Resources provider │ ├── tools.py # Tools provider │ └── prompts.py # Prompts provider └── tests/ ├── __init__.py └── test_server.py # Тесты

MCP SDK

Спецификация

Статус

1.0+

2024-11-05

Актуальная

0.x

2024-05-31

Устаревшая

Поле

Тип

Обязательное

Описание

command

string

Да

Команда для запуска (python, node, etc.)

args

array

Нет

Аргументы командной строки

cwd

string

Нет

Рабочая директория процесса

env

object

Нет

Переменные окружения

================================================== MCP Development Environment Check ================================================== Python version: 3.11.7 ✅ Python version OK MCP version: 1.0.0 ✅ MCP SDK installed 2026-03-17 10:00:00 - __main__ - INFO - Logging test ✅ Logging configured ================================================== ✅ All checks passed! Ready to develop.

Инструмент

Назначение

Python 3.10+

Требуется для асинхронных возможностей MCP SDK

Poetry

Управление зависимостями и виртуальными окружениями

MCP SDK

Официальная библиотека для создания серверов

Claude Desktop

Тестирование интеграции с LLM

MCP Inspector

Отладка серверов, просмотр запросов

.env

Безопасное хранение секретов