Model Context Protocol, или MCP, связывает AI-клиент с внешними инструментами. В Claude Desktop такой связкой могут быть локальная папка, база SQLite, поисковый сервис или собственный сервер, написанный на Python или TypeScript.
Практическая ценность MCP не в том, что модель «получает полный доступ к компьютеру». Хорошая конфигурация делает обратное: выдаёт только необходимые инструменты, ограничивает рабочие директории и хранит секреты отдельно от основного файла настроек.
Ниже — сценарий для разработчика или технического автора, которому нужно подключить несколько локальных инструментов к Claude Desktop и затем добавить собственный API без чрезмерных разрешений.
Как устроено подключение
Claude Desktop выступает клиентом MCP. Он запускает локальные серверы как дочерние процессы и обменивается с ними сообщениями через STDIO. Сервер объявляет доступные инструменты, а клиент показывает их модели в контексте диалога.
В типичной схеме есть три элемента:
- Claude Desktop — приложение, в котором ведётся диалог;
- MCP-сервер — отдельный процесс с инструментами;
- ресурс — файлы, база данных или внешний API, к которому сервер обращается.
Для локальной работы чаще всего используется STDIO. Удалённые варианты требуют отдельной настройки транспорта, авторизации и сетевой защиты, поэтому их не стоит добавлять в первую конфигурацию без необходимости.
MCP не превращает модель в автономного администратора системы. Модель может попросить вызвать инструмент, но фактические права определяются процессом сервера, операционной системой, настройками базы и ограничениями самого инструмента.
Где находится файл конфигурации
Путь зависит от операционной системы:
| Система | Файл конфигурации |
|---|---|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | расположение зависит от способа установки и сборки приложения |
Перед редактированием сохраните резервную копию файла. Конфигурация должна быть корректным JSON: без комментариев, лишних запятых и повторяющихся ключей.
Минимальная структура выглядит так:
json
{
«mcpServers»: {}
}
Каждый сервер получает собственное имя внутри объекта `mcpServers`. В значении указываются команда запуска, аргументы и, при необходимости, переменные окружения.
Пример с отдельным сервером:
json
{
«mcpServers»: {
«project-files»: {
«command»: «npx»,
«args»: [
«-y»,
«@modelcontextprotocol/server-filesystem»,
«/Users/username/projects/demo»
]
}
}
}
Пути в примере нужно заменить на реальные. Не используйте относительные пути: Claude Desktop может запускать процесс с другой текущей директорией, и сервер не найдёт ресурс.
Названия и доступность npm-пакетов меняются, поэтому перед установкой проверяйте актуальную документацию конкретного сервера. Старые примеры из блогов могут содержать устаревшие имена пакетов или параметры запуска.
Подключение файловой системы
Сервер файловой системы подходит для работы с исходным кодом, документацией и тестовыми материалами. Начните с одной отдельной директории, а не с домашнего каталога пользователя.
В конфигурации можно разрешить несколько папок:
json
{
«mcpServers»: {
«project-files»: {
«command»: «npx»,
«args»: [
«-y»,
«@modelcontextprotocol/server-filesystem»,
«/Users/username/projects/demo»,
«/Users/username/projects/docs»
]
}
}
}
Для Windows используйте корректный путь в формате, который понимает установленная оболочка. При проблемах с обратными слешами проверьте, что JSON содержит экранированные символы, например:
json
{
«mcpServers»: {
«project-files»: {
«command»: «npx»,
«args»: [
«-y»,
«@modelcontextprotocol/server-filesystem»,
«C:\\Users\\username\\projects\\demo»
]
}
}
}
После перезапуска Claude Desktop сервер должен появиться в списке доступных инструментов. Проверьте его на безопасной операции: попросите перечислить файлы в тестовой папке, а не изменить существующий документ.
Практическое правило: отдельная рабочая директория лучше широкого доступа. Если агенту нужно читать исходный код, ему не требуется доступ к SSH-ключам, архиву документов или папке с резервными копиями.
Работа с SQLite
SQLite удобно подключать к копии аналитической или тестовой базы. Это позволяет задавать вопросы по данным на естественном языке, не открывая для модели рабочую базу приложения.
Пример конфигурации:
json
{
«mcpServers»: {
«analytics-db»: {
«command»: «npx»,
«args»: [
«-y»,
«@modelcontextprotocol/server-sqlite»,
«/Users/username/data/analytics-copy.db»
]
}
}
}
Перед подключением сделайте копию файла базы и убедитесь, что в ней нет лишних персональных данных. Даже если задача начинается с `SELECT`, набор доступных инструментов конкретного сервера может включать операции изменения схемы или записей. Это нужно проверить в документации и исходном коде выбранной реализации.
Для первого теста используйте запрос, который не меняет данные:
text
Покажи список таблиц и для каждой укажи количество строк. Ничего не изменяй в базе.
После этого можно попросить сформировать SQL для конкретного отчёта, но полезно разделять два шага: сначала получить запрос для проверки, затем отдельно разрешить его выполнение.
Если сервер поддерживает только путь к файлу и не умеет ограничивать SQL-операции, защита должна быть на уровне самой базы и операционной системы. Подключение к production-файлу в таком случае не оправдано.
Внешние API и секреты
Сервер, обращающийся к внешнему API, должен получать ключ через переменную окружения. Не вставляйте токен в `args`, исходный код или публичный репозиторий.
Пример конфигурации:
json
{
«mcpServers»: {
«internal-api»: {
«command»: «python»,
«args»: [
«/Users/username/mcp/internal_api_server.py»
],
«env»: {
«INTERNAL_API_TOKEN»: «значение_из_локального_секретного_хранилища»
}
}
}
}
Такой вариант всё равно хранит секрет в конфигурации Claude Desktop, поэтому для чувствительных ключей предпочтительнее запускать промежуточный скрипт, который получает переменную из системного хранилища, или использовать отдельный локальный launcher.
Серверу достаточно разрешить только нужные операции. Если приложению требуется чтение задач из трекера, не добавляйте методы удаления, изменения прав пользователей и управления billing. Чем меньше поверхность API, тем проще проверить действия модели.
Перед подключением внешнего сервиса проверьте:
| Что проверить | Зачем это нужно |
|---|---|
| Объём разрешений токена | Ограничить чтение и запись |
| Срок действия ключа | Уменьшить последствия утечки |
| Лимиты запросов | Не допустить неожиданный расход |
| Логи обращений | Понять, какой инструмент вызывался |
| Обработка ошибок | Не раскрывать токены и внутренние данные |
Пример собственного сервера на Python
Собственный MCP-сервер оправдан, когда готовая реализация не подходит по разрешениям или формату данных. Хороший первый пример — безопасный инструмент, который возвращает статус задачи по её идентификатору из локального JSON-файла.
Ниже приведён каркас. Точный импорт MCP SDK зависит от версии установленного пакета, поэтому перед запуском сверяйте его с актуальной документацией SDK.
python
import json
import os
from pathlib import Path
from mcp.server.fastmcp import FastMCP
mcp = FastMCP(«task-status»)
DATA_FILE = Path(
os.environ.get(«TASK_DATA_FILE», «./data/tasks.json»)
).resolve()
ALLOWED_ROOT = Path(
os.environ.get(«TASK_DATA_ROOT», «./data»)
).resolve()
def load_tasks() -> list[dict]:
if ALLOWED_ROOT not in DATA_FILE.parents:
raise ValueError(«Файл находится вне разрешённой директории»)
with DATA_FILE.open(«r», encoding=»utf-8″) as file:
data = json.load(file)
if not isinstance(data, list):
raise ValueError(«Ожидался JSON-массив задач»)
return data
@mcp.tool()
def get_task_status(task_id: str) -> str:
«»»Возвращает статус задачи по её идентификатору.»»»
for task in load_tasks():
if str(task.get(«id»)) == task_id:
return json.dumps(
{
«id»: task.get(«id»),
«title»: task.get(«title»),
«status»: task.get(«status»),
},
ensure_ascii=False,
)
return json.dumps(
{«error»: «Задача не найдена»},
ensure_ascii=False,
)
if name == «main»:
mcp.run(transport=»stdio»)
В этом варианте сервер:
- предоставляет только один инструмент;
- читает данные из заранее выбранного файла;
- не принимает произвольный путь от модели;
- не имеет операции записи;
- возвращает ограниченный набор полей.
Положите данные, например, в `data/tasks.json`:
json
[
{
«id»: «42»,
«title»: «Проверить интеграцию»,
«status»: «in_progress»
}
]
Затем добавьте сервер в конфигурацию:
json
{
«mcpServers»: {
«task-status»: {
«command»: «python»,
«args»: [
«/Users/username/mcp/task_status.py»
],
«env»: {
«TASK_DATA_FILE»: «/Users/username/mcp/data/tasks.json»,
«TASK_DATA_ROOT»: «/Users/username/mcp/data»
}
}
}
}
В Windows вместо `python` может понадобиться `py` или полный путь к интерпретатору виртуального окружения. Если сервер использует зависимости из виртуального окружения, указывайте исполняемый файл этого окружения, а не рассчитывайте на глобальную установку пакетов.
Проверка после перезапуска
После изменения `claude_desktop_config.json` полностью перезапустите Claude Desktop. Простого закрытия окна может быть недостаточно, если приложение осталось работать в фоне.
Проверяйте подключение по порядку:
Убедитесь, что JSON проходит синтаксическую проверку.
Запустите команду сервера вручную в терминале.
3. Проверьте существование всех файлов и директорий.
4. Запустите Claude Desktop заново.
5. Откройте список инструментов и найдите имя сервера.
6. Выполните безопасный вызов без записи данных.
7. Проверьте лог приложения, если сервер исчезает после запуска.
Типичные причины ошибки:
- команда недоступна в окружении Claude Desktop;
- путь содержит ошибку или у процесса нет прав;
- пакет сервера больше не существует под указанным именем;
- файл конфигурации содержит невалидный JSON;
- переменная окружения не передалась дочернему процессу;
- сервер завершился из-за исключения при импорте;
- инструмент ожидает другой формат аргументов.
Запуск из терминала и запуск из Claude Desktop могут использовать разные `PATH`, виртуальное окружение и рабочую директорию. Поэтому команда, которая работает в интерактивном shell, не всегда запускается из приложения. В сомнительных случаях укажите абсолютные пути к Python, Node.js и файлам проекта.
Минимальные меры безопасности
MCP-сервер нужно оценивать как обычную программу с доступом к данным, а не как безобидное расширение чата.
Перед использованием проверьте:
- источник кода и дату последнего обновления;
- список инструментов, которые сервер объявляет;
- команды, выполняемые при установке и запуске;
- права файловой системы;
- передачу данных во внешние сервисы;
- наличие операций записи, удаления и выполнения команд.
Для локального проекта используйте отдельного системного пользователя или хотя бы отдельную директорию. Не подключайте к Claude Desktop папки с приватными ключами, файлами паролей и резервными копиями.
API-ключи храните вне исходного кода и не вставляйте в сообщения. Если токен уже попал в конфигурацию, историю терминала или репозиторий, отзовите его и выпустите новый.
Для баз данных применяйте копии, read-only-права и отдельные учётные данные. Для инструментов записи добавьте подтверждение на стороне сервера: например, разрешайте изменение только после явного параметра `confirm=true` или запускайте изменения через отдельную команду.
Что подключать первым
Для большинства локальных сценариев достаточно начать с двух серверов:
файловая система с одной рабочей папкой;
SQLite с копией тестовой базы.
Такой набор показывает, как Claude работает с документами и структурированными данными, но не создаёт сразу лишний сетевой периметр.
Внешний поиск или API добавляйте после проверки локальной конфигурации. Собственный сервер имеет смысл писать, когда нужно:
- скрыть сложность внутреннего API;
- ограничить набор разрешённых операций;
- привести ответы к удобному для модели формату;
- добавить проверку параметров;
- вести отдельный журнал вызовов.
После каждого изменения тестируйте один инструмент, а не весь набор сразу. Если добавить пять серверов одновременно, найти источник ошибки будет заметно сложнее.
Источники и проверка совместимости
Документация и репозитории MCP меняются, поэтому перед публикацией конфигурации проверяйте актуальные названия пакетов и API SDK:
- Документация Anthropic по MCP
- Архитектура MCP
- Официальный сайт Model Context Protocol
- Репозиторий MCP Servers
- Документация Claude Desktop
Главное практическое правило простое: подключайте минимальный набор инструментов, выдавайте им минимальные права и сначала проверяйте операции чтения. Так MCP в Claude Desktop становится управляемым рабочим интерфейсом для AI-агента, а не неконтролируемым доступом к компьютеру.