strava-openapi-mcp

Servidor MCP local en Python que actúa como proxy genérico entre un cliente MCP—especialmente OpenCode—y la API REST de Strava. Las herramientas no se implementan endpoint por endpoint: se generan al inicio a partir de la especificación oficial Swagger 2.0 de Strava.

El repositorio contiene una copia de la especificación y sus documentos de esquema referenciados. Por lo tanto, el inicio no requiere acceso a Internet para construir la lista de herramientas. El comando update-spec actualiza la copia del usuario tras la validación.

Arquitectura

openapi.py carga y valida Swagger, resuelve referencias locales y normaliza las operaciones. tools.py transforma cada operación en una herramienta MCP con un JSON Schema generado. client.py construye URLs, parámetros, cuerpos JSON y formularios multipart sin conocer los endpoints de Strava individualmente. auth.py gestiona el flujo OAuth local y la renovación de tokens. server.py expone todo a través de MCP stdio, mientras que cli.py proporciona comandos de mantenimiento.

La especificación actualmente publicada por Strava es Swagger 2.0, con info.version 3.0.0. El paquete se trata intencionadamente como datos reemplazables: si aparece un nuevo endpoint en la especificación, se descubre automáticamente.

Related MCP server: MCP OpenAPI Connector

Requisitos previos e instalación local

Se recomiendan Python 3.12+ y uv.

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

Inicie el servidor MCP con:

uv run strava-mcp

El servidor permanece activo en el transporte MCP stdin/stdout. Los registros de la aplicación se envían a stderr. No se debe escribir ningún registro de diagnóstico en stdout durante el transporte stdio.

Crear una aplicación de Strava

1. Abra https://www.strava.com/settings/api.

2. Cree una aplicación y anote su Client ID y Client Secret.

3. Strava acepta localhost y 127.0.0.1 como dominios de callback. El callback predeterminado es http://127.0.0.1:8765/callback.

Las credenciales se pueden proporcionar a través del entorno:

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

O en ~/.config/strava-mcp/credentials.json con permisos 0600:

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

Las variables de entorno tienen prioridad. El secreto nunca se muestra ni se escribe en los registros.

OAuth

Ejecute una vez:

strava-mcp auth

El navegador abre la página de autorización de Strava. El callback local intercambia el código de autorización por access_token, refresh_token, expires_at y los ámbitos concedidos. Los tokens se almacenan en ~/.config/strava-mcp/tokens.json con permisos 0600. El servidor renueva automáticamente los tokens de acceso caducados y persiste un token de renovación rotatorio cuando Strava devuelve uno.

Por defecto, se solicitan todos los ámbitos declarados por la especificación. Para solicitar un subconjunto:

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

Las descripciones oficiales se analizan para inferir ámbitos explícitos. Los endpoints de lectura que aceptan activity:read o activity:read_all se representan como alternativas. Un ámbito condicional—como activity:read_all para una actividad privada—se muestra al LLM, y el error original de Strava permanece visible.

Configuración

Variables admitidas:

También se aceptan los alias STRAVA_MCP_ALLOW_WRITE y STRAVA_MCP_ALLOW_DELETE. strava-mcp show-config muestra solo una vista de configuración no secreta.

Los valores recomendados son STRAVA_ALLOW_WRITE=true y STRAVA_ALLOW_DELETE=false. Los métodos POST, PUT y PATCH no están bloqueados por defecto. Los métodos DELETE se generan cuando la especificación los contiene, pero se filtran de la lista de herramientas MCP mientras STRAVA_ALLOW_DELETE=false.

Primer inicio

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

La copia de la especificación del usuario tiene prioridad. Si no existe, se utiliza la especificación oficial incluida sin descargar nada al inicio.

Actualizar la especificación

strava-mcp update-spec

El comando descarga STRAVA_OPENAPI_URL, valida el documento Swagger y luego descarga los documentos JSON referenciados. La copia existente se reemplaza solo después de que todo el proceso de descarga y validación tenga éxito. Se muestran la versión informada y el número de esquemas referenciados.

Para forzar una ruta diferente:

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

Instalación directa con uvx desde Git

El pyproject.toml declara el ejecutable y todas las dependencias. No se requiere instalación manual de Python ni clonación:

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

Para usar inmediatamente un nuevo commit a pesar de la caché de uv:

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

Configuración de OpenCode

Añada el servidor a la configuración de OpenCode:

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

Exporte las variables en el entorno que lanza OpenCode, o use credentials.json, en lugar de comprometer secretos en este archivo. Ejecute strava-mcp auth una vez para la misma cuenta local antes de iniciar OpenCode.

Herramientas generadas y ejemplos

Los nombres se derivan de operationId, normalizados a snake case, con un prefijo de método HTTP añadido solo cuando es necesario para evitar ambigüedad. Por ejemplo, con la especificación actual:

Los parámetros del cuerpo UpdatableActivity se aplanan en la herramienta PUT. El agente puede, por tanto, realizar llamadas conceptualmente equivalentes:

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.")

Otros ejemplos de solicitudes en lenguaje natural:

• “Lista mis últimas actividades de carrera”: use get_logged_in_athlete_activities y luego filtre los resultados devueltos.

• “Lee los detalles de la actividad 123”: use get_activity_by_id(id=123).

• “Obtén los streams de distancia y frecuencia cardíaca para 123”: use get_activity_streams(id=123, keys=["distance", "heartrate"], key_by_type=true).

• “Obtén mis estadísticas”: obtenga el atleta autenticado y luego use get_stats(id=...).

La paginación está completamente controlada por los parámetros de la especificación (page, per_page, before, after, page_size, after_cursor, etc.). El servidor nunca inicia automáticamente una secuencia larga de solicitudes de página.

Escrituras y operaciones peligrosas

Las descripciones MCP incluyen This operation modifies Strava data para POST/PUT/PATCH y WARNING para DELETE. Si STRAVA_ALLOW_WRITE=false, las herramientas de escritura devuelven un error explícito. Si STRAVA_ALLOW_DELETE=false, las herramientas DELETE están ausentes de list_tools y las llamadas directas se rechazan.

Los errores HTTP conservan el estado, el endpoint, el mensaje de Strava y las cabeceras de límite de velocidad disponibles, por ejemplo:

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

Una respuesta 204 se convierte en el objeto mínimo { "status": "success", "http_status": 204 }. Las respuestas JSON conservan los nombres de campo de Strava.

Comandos 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 es útil para diagnosticar un cliente MCP que rechaza un esquema. Las palabras clave JSON Schema como required se muestran en el nivel de esquema relevante; una propiedad de Strava llamada required permanece bajo properties.

Pruebas y desarrollo

uv run pytest
uv run ruff check .

Las pruebas usan transportes HTTP simulados y no contactan con Strava. Las pruebas de integración contra Strava no se ejecutan automáticamente a propósito.

Solución de problemas

• No Strava authorization found: ejecute strava-mcp auth con las credenciales correctas.

• OAuth scope missing: ejecute strava-mcp auth de nuevo con el ámbito solicitado en STRAVA_OAUTH_SCOPES.

• Spec update aborted: la copia local anterior permanece intacta; compruebe la red o elimine un STRAVA_OPENAPI_PATH personalizado.

• No hay herramientas DELETE: este es el comportamiento predeterminado; establezca STRAVA_ALLOW_DELETE=true y reinicie.

• Error MCP relacionado con stdout: no añada llamadas print al código del servidor; los registros deben usar logging configurado para stderr.

• Puerto OAuth ya en uso: establezca STRAVA_CALLBACK_PORT a un puerto disponible y, si es necesario, registre el dominio localhost en la aplicación de Strava.

Seguridad

El secreto de cliente, el token de acceso y el token de renovación nunca se incluyen en registros, descripciones MCP o mensajes de error. Los archivos locales de credenciales y tokens son ignorados por Git y se escriben con permisos 0600. Nunca comprometa .env, credentials.json o tokens.json.