Gosar MCP Server

MCP-сервер, который позволяет Claude вызывать Gosar API от имени пользователя, с аутентификацией через OAuth 2.0 + PKCE от Gosar.

Он действует как мост:

• Для Claude (MCP-клиента) он ведёт себя как полноценный OAuth-сервер авторизации — обрабатывает динамическую регистрацию клиентов и выдаёт собственные кратковременные токены.

• Для Gosar он является единственным предварительно зарегистрированным OAuth-клиентом (публичным, только с PKCE), который выполняет реальный обмен Authorization Code + PKCE, описанный в руководстве по интеграции Gosar.

Предварительные требования

• Python 3.11+

• OAuth-клиент Gosar, зарегистрированный в команде Gosar (см. «Что нам нужно от вас» в руководстве по интеграции) — вам нужны client_id и одобренный redirect URI.

• ngrok (или аналогичный инструмент), если вы хотите тестировать с реальным Gosar API — redirect URI Gosar должен быть HTTPS и точно совпадать, а Claude также нужен HTTPS-URL для подключения удалённого MCP-сервера.

Related MCP server: Strava MCP Server

1. Установка зависимостей

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Настройка .env

Скопируйте имеющиеся значения в .env в корне проекта:

# Real values from the Gosar team
GOSAR_API_BASE_URL=https://api.gosar.example
GOSAR_CLIENT_ID=your-registered-client-id
GOSAR_SCOPES=applications.read applications.write

# Your server's own public HTTPS URL (e.g. your ngrok URL). Gosar's registered
# redirect_uri must be exactly this + GOSAR_REDIRECT_PATH.
MCP_PUBLIC_BASE_URL=https://your-tunnel.ngrok-free.app
GOSAR_REDIRECT_PATH=/gosar/callback

MCP_HOST=0.0.0.0
MCP_PORT=8000

# Generate once and keep stable — see below
JWT_SIGNING_KEY=

Сгенерируйте ключ подписи (Gosar — публичный клиент без секрета, поэтому его нельзя получить автоматически — он обязателен):

python -c "import secrets; print(secrets.token_urlsafe(32))"

Вставьте вывод в JWT_SIGNING_KEY. Держите его одинаковым между перезапусками, иначе каждый подключённый пользователь будет выходить из системы.

3. Откройте ваш сервер через HTTPS (для реального тестирования Gosar)

Claude и Gosar оба требуют HTTPS. В отдельном терминале:

ngrok http 8000

Скопируйте URL https://...ngrok-free.app в MCP_PUBLIC_BASE_URL в .env и отправьте {MCP_PUBLIC_BASE_URL}/gosar/callback команде Gosar как ваш зарегистрированный redirect URI.

4. Запуск сервера

source .venv/bin/activate
python main.py

Вы должны увидеть:

Starting MCP server 'Gosar' with transport 'http' on http://0.0.0.0:8000/mcp
Uvicorn running on http://0.0.0.0:8000

Автоперезагрузка при изменении кода

python main.py не перезагружается — mcp.run() блокирует выполнение и владеет собственным процессом uvicorn, который нельзя передать файловому наблюдателю для перезагрузки. Для разработки запускайте ASGI-приложение в gosar_mcp/asgi.py напрямую под uvicorn:

uvicorn gosar_mcp.asgi:app --reload --reload-include ".env" --host 0.0.0.0 --port 8000

• --reload перезапускает рабочий процесс при изменении любого файла .py.

• --reload-include ".env" также перезапускает его при редактировании .env (uvicorn по умолчанию следит только за Python-файлами, а переменные окружения читаются только один раз при запуске процесса, поэтому без этого флага изменение .env потребует ручного перезапуска).

• Держите порт в соответствии с тем, куда указывает ваш ngrok-туннель.

5. Проверка OAuth-связки

При запущенном сервере убедитесь, что метаданные обнаружения обслуживаются:

curl -s http://127.0.0.1:8000/.well-known/oauth-authorization-server | python3 -m json.tool

Вы должны увидеть applications.read/applications.write в scopes_supported и S256 как единственный метод PKCE.

6. Подключение к Claude

В настройках коннектора Claude добавьте удалённый MCP-сервер, указав:

https://your-tunnel.ngrok-free.app/mcp

Claude зарегистрируется как OAuth-клиент на этом сервере, перенаправит пользователя через согласие, затем через реальный вход Google + экран согласия Gosar, и вернётся сюда с активным подключением. Попросите Claude вызвать инструмент whoami, чтобы подтвердить, что он аутентифицирован как ожидаемая учётная запись Gosar.

Примечания

• Хранилище токенов (регистрации клиентов + зашифрованные вышестоящие токены Gosar) по умолчанию использует подходящее для ОС зашифрованное файловое хранилище на диске — дополнительная настройка для локальной разработки не требуется. См. gosar_mcp/auth.py, чтобы указать другой бэкенд в продакшене.

• Пути конечных точек /applications в gosar_mcp/tools.py — заглушки: руководство по интеграции определяет только уровень OAuth, а не форму REST API приложений. Уточните реальные пути/полезные нагрузки у команды Gosar и скорректируйте их там.