strava-openapi-mcp

Локальный Python MCP-сервер, выступающий в роли универсального прокси между MCP-клиентом — особенно OpenCode — и REST API Strava. Инструменты не реализованы по конечным точкам: они генерируются при запуске из официальной спецификации Swagger 2.0 Strava.

Репозиторий содержит копию спецификации и связанных с ней документов схем. Поэтому для запуска не требуется доступ в Интернет для построения списка инструментов. Команда update-spec обновляет пользовательскую копию после проверки.

Архитектура

openapi.py загружает и проверяет Swagger, разрешает локальные ссылки и нормализует операции. tools.py преобразует каждую операцию в инструмент MCP с сгенерированной JSON-схемой. client.py строит URL-адреса, параметры, JSON-тела и multipart-формы, не зная конечные точки Strava по отдельности. auth.py обрабатывает локальный поток OAuth и обновление токенов. server.py предоставляет всё через MCP stdio, а cli.py предоставляет команды обслуживания.

Текущая опубликованная спецификация Strava — Swagger 2.0, с info.version 3.0.0. Пакет намеренно рассматривается как заменяемые данные: если в спецификации появляется новая конечная точка, она обнаруживается автоматически.

Related MCP server: MCP OpenAPI Connector

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

Рекомендуются Python 3.12+ и uv.

git clone https://github.com/Arbodgad/strava-openapi-mcp.git
cd strava-openapi-mcp
uv sync
uv run strava-mcp list-tools

Запустите MCP-сервер с помощью:

uv run strava-mcp

Сервер остаётся активным на транспорте MCP stdin/stdout. Журналы приложения отправляются в stderr. Во время работы stdio-транспорта в stdout не должно записываться никаких диагностических журналов.

Создание приложения Strava

1. Откройте https://www.strava.com/settings/api.

2. Создайте приложение и запишите его Client ID и Client Secret.

3. Strava принимает localhost и 127.0.0.1 в качестве доменов обратного вызова. Обратный вызов по умолчанию: http://127.0.0.1:8765/callback.

Учётные данные можно указать через переменные окружения:

export STRAVA_CLIENT_ID="..."
export STRAVA_CLIENT_SECRET="..."

Или в ~/.config/strava-mcp/credentials.json с правами 0600:

{
  "client_id": "...",
  "client_secret": "..."
}

Переменные окружения имеют приоритет. Секрет никогда не отображается и не записывается в журналы.

OAuth

Выполните один раз:

strava-mcp auth

Браузер открывает страницу авторизации Strava. Локальный обратный вызов обменивает код авторизации на access_token, refresh_token, expires_at и предоставленные области. Токены хранятся в ~/.config/strava-mcp/tokens.json с правами 0600. Сервер автоматически обновляет истёкшие токены доступа и сохраняет вращающийся refresh-токен, когда Strava возвращает его.

По умолчанию запрашиваются все области, объявленные в спецификации. Чтобы запросить подмножество:

export STRAVA_OAUTH_SCOPES="activity:read,activity:write"

Официальные описания анализируются для определения явных областей. Чтение конечных точек, принимающих либо activity:read, либо activity:read_all, представлено как альтернативы. Условная область — например, activity:read_all для приватной активности — показывается LLM, и исходная ошибка Strava остаётся видимой.

Конфигурация

Поддерживаемые переменные:

Псевдонимы STRAVA_MCP_ALLOW_WRITE и STRAVA_MCP_ALLOW_DELETE также принимаются. strava-mcp show-config отображает только несекретное представление конфигурации.

Рекомендуемые значения: STRAVA_ALLOW_WRITE=true и STRAVA_ALLOW_DELETE=false. Методы POST, PUT и PATCH по умолчанию не блокируются. Методы DELETE генерируются, когда они есть в спецификации, но фильтруются из списка инструментов MCP, пока STRAVA_ALLOW_DELETE=false.

Первый запуск

export STRAVA_CLIENT_ID="..."
export STRAVA_CLIENT_SECRET="..."
strava-mcp auth
strava-mcp list-tools
strava-mcp

Пользовательская копия спецификации имеет приоритет. Если её нет, используется встроенная официальная спецификация без загрузки чего-либо при запуске.

Обновление спецификации

strava-mcp update-spec

Команда загружает STRAVA_OPENAPI_URL, проверяет документ Swagger, а затем загружает связанные JSON-документы. Существующая копия заменяется только после успешного завершения всего процесса загрузки и проверки. Отображаются сообщённая версия и количество связанных схем.

Чтобы указать другой путь:

STRAVA_OPENAPI_PATH="$HOME/.config/strava-mcp/openapi.json" strava-mcp update-spec

Прямая установка с помощью uvx из Git

В pyproject.toml объявлены исполняемый файл и все зависимости. Ручная установка Python или клонирование не требуются:

uvx --from git+https://github.com/Arbodgad/strava-openapi-mcp strava-mcp auth
uvx --from git+https://github.com/Arbodgad/strava-openapi-mcp strava-mcp

Чтобы немедленно использовать новый коммит, несмотря на кэш uv:

uvx --refresh --from git+https://github.com/Arbodgad/strava-openapi-mcp strava-mcp

Конфигурация OpenCode

Добавьте сервер в конфигурацию OpenCode:

{
  "mcp": {
    "strava": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/Arbodgad/strava-openapi-mcp",
        "strava-mcp"
      ],
      "enabled": true
    }
  }
}

Экспортируйте переменные в окружении, которое запускает OpenCode, или используйте credentials.json, вместо того чтобы сохранять секреты в этом файле. Выполните strava-mcp auth один раз для той же локальной учётной записи перед запуском OpenCode.

Сгенерированные инструменты и примеры

Имена образуются из operationId, нормализуются в snake_case, с добавлением префикса HTTP-метода только при необходимости для избежания неоднозначности. Например, с текущей спецификацией:

Параметры тела UpdatableActivity уплощаются в инструмент PUT. Поэтому агент может выполнять концептуально эквивалентные вызовы:

put_update_activity_by_id(id=123456789, name="Long Z2 run")
put_update_activity_by_id(id=123456789, description="Easy aerobic endurance session, good sensations.")

Другие примеры запросов на естественном языке:

• «Список моих последних беговых активностей»: используйте get_logged_in_athlete_activities, затем отфильтруйте возвращённые результаты.

• «Прочитай детали активности 123»: используйте get_activity_by_id(id=123).

• «Получи потоки дистанции и пульса для 123»: используйте get_activity_streams(id=123, keys=["distance", "heartrate"], key_by_type=true).

• «Получи мою статистику»: получите аутентифицированного спортсмена, затем используйте get_stats(id=...).

Пагинация полностью контролируется параметрами из спецификации (page, per_page, before, after, page_size, after_cursor и т. д.). Сервер никогда не запускает автоматически длинную последовательность запросов страниц.

Запись и опасные операции

В описаниях MCP для POST/PUT/PATCH указано This operation modifies Strava data, а для DELETE — WARNING. Если STRAVA_ALLOW_WRITE=false, инструменты записи возвращают явную ошибку. Если STRAVA_ALLOW_DELETE=false, инструменты DELETE отсутствуют в list_tools, и прямые вызовы отклоняются.

Ошибки HTTP сохраняют статус, конечную точку, сообщение Strava и доступные заголовки ограничения скорости, например:

HTTP 401 Unauthorized
Endpoint: PUT /activities/{id}
Message: Invalid or expired token

Ответ 204 становится минимальным объектом { "status": "success", "http_status": 204 }. JSON-ответы сохраняют имена полей Strava.

Команды CLI

strava-mcp                       # MCP stdio server
strava-mcp auth                  # Browser OAuth + localhost callback
strava-mcp update-spec           # Validated update of the local copy
strava-mcp show-config           # Non-secret configuration
strava-mcp list-tools            # Method, endpoint, tool, and summary
strava-mcp list-tools --schemas  # Also display each inputSchema JSON

list-tools --schemas полезен для диагностики MCP-клиента, который отклоняет схему. Ключевые слова JSON Schema, такие как required, отображаются на соответствующем уровне схемы; свойство Strava с именем required остаётся в разделе properties.

Тесты и разработка

uv run pytest
uv run ruff check .

В тестах используются имитированные HTTP-транспорты, они не связываются со Strava. Интеграционные тесты против Strava намеренно не запускаются автоматически.

Устранение неполадок

• No Strava authorization found: выполните strava-mcp auth с правильными учётными данными.

• OAuth scope missing: выполните strava-mcp auth снова с областью, запрошенной в STRAVA_OAUTH_SCOPES.

• Spec update aborted: предыдущая локальная копия остаётся нетронутой; проверьте сеть или удалите пользовательский STRAVA_OPENAPI_PATH.

• Нет инструментов DELETE: это поведение по умолчанию; установите STRAVA_ALLOW_DELETE=true и перезапустите.

• Ошибка MCP, связанная с stdout: не добавляйте вызовы print в код сервера; журналы должны использовать логирование, настроенное для stderr.

• Порт OAuth уже используется: установите STRAVA_CALLBACK_PORT на доступный порт и, при необходимости, зарегистрируйте домен localhost в приложении Strava.

Безопасность

Секрет клиента, токен доступа и refresh-токен никогда не включаются в журналы, описания MCP или сообщения об ошибках. Локальные файлы учётных данных и токенов игнорируются Git и записываются с правами 0600. Никогда не коммитьте .env, credentials.json или tokens.json.