# local_computer (remote) — доступ ИИ к компьютеру через claude.ai / ChatGPT

MCP-сервер на Python, который даёт claude.ai или ChatGPT доступ к файлам и
терминалу твоего компьютера. В отличие от локального stdio-сервера, этот
говорит по Streamable HTTP и закрыт GitHub OAuth, поэтому его можно добавить
удалённым коннектором в claude.ai (Settings → Connectors), как только он
доступен по публичному https-адресу.

## Установка одной командой

macOS / Linux:
```
curl -fsSL https://raw.githubusercontent.com/ApsidD/local-computer-mcp/main/install.sh | sh
```

Windows (PowerShell):
```
irm https://raw.githubusercontent.com/ApsidD/local-computer-mcp/main/install.ps1 | iex
```

Скрипт проверит Python (поставит, если нет), скачает проект, поставит
зависимости в изолированный `.venv`, при желании поставит Tailscale и запустит
визард настройки. После него сервер запускается через `run.py`.

## Фоновый сервис (автозапуск)

Чтобы сервер работал в фоне и стартовал сам, на любой из трёх ОС:
```
python service.py install     # поставить
python service.py status      # проверить
python service.py uninstall   # убрать
```
Под капотом: systemd user service на Linux, launchd LaunchAgent на macOS,
Scheduled Task при входе в систему на Windows. Сервис запускает `run.py`
(сервер плюс туннель).

## Быстрая установка (терминальный визард)

Не хочешь возиться руками, запусти визард, он всё спросит и настроит:

```
pip install fastmcp
python setup.py     # ответь на вопросы (GitHub-логин, секреты, способ вывода наружу)
python run.py       # поднимает сервер и туннель одной командой
```

`setup.py` сам сгенерирует `.env`, ключ подписи токенов и подскажет точный
callback для GitHub OAuth App. `run.py` запустит сервер и выбранный туннель
(Tailscale Funnel или ngrok). Дальше в claude.ai вставляешь адрес `BASE_URL/mcp`.

Если хочешь понимать, что под капотом, ниже всё то же самое вручную.

## Инструменты (17)

Чтение: `list_directory`, `read_file`, `bulk_read`, `search_files`, `search_text`, `get_system_info`
Картинки и видео: `view_images` (ИИ видит картинки), `video_screenshots` (кадры из видео, нужен ffmpeg)
Запись: `write_file`, `append_file`, `edit_file`, `multi_edit`, `make_directory`, `move_path`, `copy_path`, `delete_path`
Терминал: `run_command`

## Что нужно

- Python 3.10+ и `pip install fastmcp`
- ffmpeg в системе (только для `video_screenshots`)
- Публичный https-адрес для сервера. Проще всего туннель (cloudflared, бесплатно)
- Аккаунт GitHub (для OAuth)

## Шаг 1. GitHub OAuth App

1. Открой github.com/settings/developers → OAuth Apps → New OAuth App.
2. Заполни:
   - Application name: любое (например, local_computer MCP)
   - Homepage URL: твой будущий публичный адрес
   - Authorization callback URL: твой адрес + `/auth/callback`
     (например, `https://your-tunnel.trycloudflare.com/auth/callback`)
3. Сохрани Client ID и сгенерируй Client Secret.

Callback должен совпадать с адресом точь-в-точь. Если адрес туннеля поменяется,
этот URL надо обновить и в GitHub, и в `.env`.

## Шаг 2. Настройка .env

Скопируй `.env.example` в `.env` и заполни:
- `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` из шага 1
- `BASE_URL` — публичный адрес сервера (тот же, что в callback, без `/auth/callback`)
- `ALLOWED_GITHUB_USERS=ApsidD` — твой GitHub-логин. Без него внутрь пустит любого.
- `ALLOWED_ROOT` — корень для файловых инструментов (пусто = домашняя папка)
- `JWT_SIGNING_KEY` (необязательно) — чтобы не логиниться заново после рестарта

## Шаг 3. Публичный адрес

Серверу нужен публичный https-адрес, чтобы claude.ai/ChatGPT до него достучались.
Три варианта, по убыванию удобства стабильного адреса:

**Tailscale Funnel** (если пользуешься Tailscale). Одна команда выставляет
локальный порт в публичный интернет по HTTPS с валидным сертификатом на адресе
вида `https://машина.твой-tailnet.ts.net`:
```
tailscale funnel 8000
```
Адрес стабильный, это и есть `BASE_URL`. Разово надо включить Funnel для ноды
в ACL (Tailscale подскажет ссылку при первом запуске). Обычный Tailscale без
Funnel не подойдёт, это приватная сеть, claude.ai в неё не входит.

**ngrok** (если Tailscale нет). Бесплатный аккаунт даёт один постоянный домен
`имя.ngrok-free.app`. Создаёшь его в дашборде, потом:
```
ngrok http 8000 --url=https://имя.ngrok-free.app
```

**cloudflared** (если есть свой домен в Cloudflare). Именованный туннель даёт
стабильный адрес на твоём домене. Быстрый `cloudflared tunnel --url
http://localhost:8000` тоже работает, но адрес меняется при каждом запуске,
поэтому только для разовой проверки.

Чем бы ни выставлял, `BASE_URL` в `.env` и callback в GitHub должны совпадать
с этим адресом.

## Шаг 4. Запуск сервера

```
pip install fastmcp
python server.py
```
Сервер поднимется на `http://127.0.0.1:8000/mcp`, а наружу его выставит туннель.

## Шаг 5. Подключение в claude.ai

1. claude.ai → Settings → Connectors → Add custom connector.
2. URL: твой `BASE_URL` + `/mcp` (например, `https://your-tunnel.trycloudflare.com/mcp`).
3. Нажми Connect. Откроется вход через GitHub, авторизуешься.
4. В чате появятся инструменты сервера. Claude будет спрашивать подтверждение
   на каждый вызов. Скажи «покажи файлы на рабочем столе» для проверки.

Коннектор, добавленный в claude.ai, работает и в мобильных приложениях Claude.

## ChatGPT

ChatGPT тоже работает с удалёнными MCP-серверами (через коннекторы в режиме
разработчика). URL тот же, `BASE_URL` + `/mcp`. Детали интерфейса у ChatGPT
меняются, так что если упрётся, сверься с актуальной справкой ChatGPT по MCP.

## Безопасность (важно)

- Этот сервер открывает доступ к терминалу твоего ПК наружу. GitHub OAuth плюс
  `ALLOWED_GITHUB_USERS` это твоя главная защита. Не оставляй allowlist пустым.
- Файловые инструменты заперты в `ALLOWED_ROOT`, но `run_command` запускает
  команды от твоего пользователя и периметром не ограничен.
- Подтверждение каждого вызова в клиенте оставляй включённым.
- Туннель даёт https снаружи; локально сервер слушает 127.0.0.1, это нормально.

## Кросс-платформенность

Код работает на Windows, Mac и Linux (Python 3.10+ и `pip install fastmcp`).
`run_command` использует родную оболочку системы (cmd на Windows, sh на
Mac/Linux), `video_screenshots` требует установленного ffmpeg.

## Проверка

```
python server.py --help     # описание и переменные
```

## Автор и лицензия

Автор: Олег Горбунов · NovaVisual · Telegram @NovaVisual_club_RU · GitHub @ApsidD

- Код: PolyForm Noncommercial License 1.0.0 (файл `LICENSE`).
- Гайды и тексты: CC BY-NC 4.0 (файл `LICENSE-GUIDES.md`).

Коротко: бери, изучай и переделывай с указанием автора. Зарабатывать на этом
или на производных нельзя.