Alpha Vantage

Accede a datos del mercado de valores en tiempo real e históricos desde la API de Alpha Vantage.

GitHub
75
Prueba este MCPPatrocinado

Documentación

✅ Servidor MCP oficial de Alpha Vantage

smithery badge Verified on MseeP

Un servidor MCP para la API de datos del mercado de valores, la API de Alphavantage.

Alpha Vantage Server MCP server

URL del servidor MCP: https://mcp.alphavantage.co

PyPi: https://pypi.org/project/alphavantage-mcp/

Configuración

Cómo obtener una clave de API

  1. Regístrate para obtener una clave gratuita de la API de Alphavantage
  2. Añade la clave de API a tus variables de entorno como ALPHAVANTAGE_API_KEY

Instalación

Opción 1: Usando uvx (Recomendado)

La forma más sencilla de usar el servidor MCP de AlphaVantage es con uvx:

# Run directly without installation
uvx alphavantage-mcp

# Or with specific arguments
uvx alphavantage-mcp --server http --port 8080

Opción 2: Usando pip

pip install alphavantage-mcp
alphavantage-mcp

Opción 3: Desde el código fuente

git clone https://github.com/calvernaz/alphavantage.git
cd alphavantage
uv run alphavantage

Modos del servidor

El servidor de AlphaVantage puede ejecutarse en dos modos diferentes:

Servidor Stdio (Predeterminado)

Este es el modo estándar del servidor MCP utilizado para herramientas como Claude Desktop.

alphavantage
# or explicitly:
alphavantage --server stdio

Servidor HTTP Streamable

Este modo proporciona actualizaciones en tiempo real mediante transmisión HTTP.

alphavantage --server http --port 8080

Servidor HTTP Streamable con autenticación OAuth 2.1

Este modo añade autenticación OAuth 2.1 al servidor HTTP, siguiendo la especificación MCP para acceso seguro.

alphavantage --server http --port 8080 --oauth

Configuración de OAuth

Al usar la bandera --oauth, el servidor requiere configuración de OAuth 2.1 mediante variables de entorno:

Variables de entorno requeridas:

export OAUTH_AUTHORIZATION_SERVER_URL="https://your-auth-server.com/realms/your-realm"
export OAUTH_RESOURCE_SERVER_URI="https://your-mcp-server.com"

Variables de entorno opcionales:

# Token validation method (default: jwt)
export OAUTH_TOKEN_VALIDATION_METHOD="jwt"  # or "introspection"

# For JWT validation
export OAUTH_JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
export OAUTH_JWT_ALGORITHM="RS256"  # default

# For token introspection validation
export OAUTH_INTROSPECTION_ENDPOINT="https://your-auth-server.com/realms/your-realm/protocol/openid-connect/token/introspect"
export OAUTH_INTROSPECTION_CLIENT_ID="your-client-id"
export OAUTH_INTROSPECTION_CLIENT_SECRET="your-client-secret"

# Optional: Required scopes (space-separated)
export OAUTH_REQUIRED_SCOPES="mcp:access mcp:read"

# Optional: Enable session binding for additional security (default: true)
export OAUTH_SESSION_BINDING_ENABLED="true"

Funciones de OAuth

La implementación de OAuth proporciona:

  • Metadatos de recursos protegidos OAuth 2.0 endpoint (/.well-known/oauth-protected-resource)
  • Autenticación con token Bearer para todas las solicitudes MCP
  • Métodos de validación JWT e introspección de tokens
  • Cumplimiento de las mejores prácticas de seguridad MCP:
    • Validación de audiencia del token (previene ataques de paso de tokens)
    • Prevención de secuestro de sesión con identificadores de sesión seguros
    • Sesiones vinculadas al usuario para mayor seguridad
    • Encabezados WWW-Authenticate adecuados para respuestas 401

Ejemplo: Configuración de Keycloak

Para pruebas con Keycloak:

# Keycloak OAuth configuration
export OAUTH_AUTHORIZATION_SERVER_URL="https://keycloak.example.com/realms/mcp-realm"
export OAUTH_RESOURCE_SERVER_URI="https://mcp.example.com"
export OAUTH_TOKEN_VALIDATION_METHOD="introspection"
export OAUTH_INTROSPECTION_ENDPOINT="https://keycloak.example.com/realms/mcp-realm/protocol/openid-connect/token/introspect"
export OAUTH_INTROSPECTION_CLIENT_ID="mcp-server"
export OAUTH_INTROSPECTION_CLIENT_SECRET="your-keycloak-client-secret"
export OAUTH_REQUIRED_SCOPES="mcp:access"

# Start server with OAuth
alphavantage --server http --port 8080 --oauth

Flujo del cliente OAuth

Cuando OAuth está habilitado, los clientes MCP deben:

  1. Descubrir el servidor de autorización mediante GET /.well-known/oauth-protected-resource
  2. Registrarse en el servidor de autorización (si se usa registro dinámico de clientes)
  3. Obtener tokens de acceso del servidor de autorización
  4. Incluir tokens en las solicitudes: Authorization: Bearer <access-token>
  5. Manejar respuestas 401/403 y renovar tokens según sea necesario

Opciones:

  • --server: Elige entre el modo de servidor stdio (predeterminado) o http
  • --port: Especifica el puerto para el servidor HTTP Streamable (predeterminado: 8080)
  • --oauth: Habilita la autenticación OAuth 2.1 (requiere --server http)

📊 Telemetría

El servidor MCP de AlphaVantage incluye métricas opcionales de Prometheus para monitoreo y observabilidad.

Habilitación de la telemetría

Establece las siguientes variables de entorno para habilitar la telemetría:

# Enable telemetry (default: true)
export MCP_TELEMETRY_ENABLED=true

# Server identification (optional)
export MCP_SERVER_NAME=alphavantage
export MCP_SERVER_VERSION=1.0.0

# Metrics server port (default: 9464)
export MCP_METRICS_PORT=9464

Endpoint de métricas

Cuando la telemetría está habilitada, las métricas de Prometheus están disponibles en:

http://localhost:9464/metrics

Métricas disponibles

El servidor recopila las siguientes métricas para cada llamada de herramienta:

  • mcp_tool_calls_total - Número total de llamadas de herramientas (etiquetadas por herramienta y resultado)
  • mcp_tool_latency_seconds - Histograma de latencia de ejecución de herramientas
  • mcp_tool_request_bytes - Histograma del tamaño de la carga útil de solicitudes
  • mcp_tool_response_bytes - Histograma del tamaño de la carga útil de respuestas
  • mcp_tool_active_concurrency - Medidor de llamadas de herramientas concurrentes activas
  • mcp_tool_errors_total - Errores totales por tipo (tiempo de espera, entrada incorrecta, conexión, desconocido)

Ejemplo de uso con telemetría

# Start server with telemetry enabled
export MCP_TELEMETRY_ENABLED=true
export MCP_SERVER_NAME=alphavantage-prod
export ALPHAVANTAGE_API_KEY=your_api_key
alphavantage --server http --port 8080

# View metrics
curl http://localhost:9464/metrics

🚀 Implementación sin servidor en AWS

Implementa el servidor MCP de AlphaVantage en AWS Lambda usando el patrón MCP sin estado para una implementación lista para producción y escalable.

Implementación rápida en AWS

cd deploy/aws-stateless-mcp-lambda
export ALPHAVANTAGE_API_KEY=your_api_key_here
./deploy.sh

Características:

  • ✅ Patrón MCP sin estado - Perfecto para el modelo de ejecución de Lambda
  • ✅ Escalado automático - Maneja cualquier carga con AWS Lambda + API Gateway
  • ✅ Rentable - Paga solo por las solicitudes (~$1-5/mes para uso típico)
  • ✅ Listo para producción - Basado en patrones oficiales de muestra de AWS
  • ✅ Soporte OAuth 2.1 - Autenticación opcional para acceso seguro

📖 Documentación completa: Consulta la Guía de implementación en AWS para instrucciones completas de configuración, pruebas, monitoreo y solución de problemas.

Uso con Claude Desktop

Opción 1: Usando uvx (Recomendado)

Añade esto a tu claude_desktop_config.json:

{
  "mcpServers": {
    "alphavantage": {
      "command": "uvx",
      "args": ["alphavantage-mcp"],
      "env": {
        "ALPHAVANTAGE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Opción 2: Desde el código fuente

Si clonaste el repositorio, usa esta configuración:

{
  "mcpServers": {
    "alphavantage": {
      "command": "uv",
      "args": [
        "--directory",
        "<DIRECTORY-OF-CLONED-PROJECT>/alphavantage",
        "run",
        "alphavantage"
      ],
      "env": {
        "ALPHAVANTAGE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Ejecutar el servidor en modo HTTP Streamable

Usando uvx:

{
  "mcpServers": {
    "alphavantage": {
      "command": "uvx",
      "args": ["alphavantage-mcp", "--server", "http", "--port", "8080"],
      "env": {
        "ALPHAVANTAGE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Desde el código fuente:

{
  "mcpServers": {
    "alphavantage": {
      "command": "uv",
      "args": [
        "--directory",
        "<DIRECTORY-OF-CLONED-PROJECT>/alphavantage",
        "run",
        "alphavantage",
        "--server",
        "http",
        "--port",
        "8080"
      ],
      "env": {
        "ALPHAVANTAGE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

📺 Video de demostración

Mira una demostración rápida del servidor MCP de Alpha Vantage en acción:

Alpha Vantage MCP Server Demo

🔧 Desarrollo y publicación

Publicación en PyPI

Este proyecto incluye scripts para publicar en PyPI y TestPyPI:

# Publish to TestPyPI (for testing)
python scripts/publish.py --test

# Publish to PyPI (production)
python scripts/publish.py

# Use uv publish instead of twine
python scripts/publish.py --test --use-uv

El script usa twine por defecto (recomendado) pero también puede usar uv publish con la bandera --use-uv.

GitHub Actions

El repositorio incluye un flujo de trabajo de GitHub Actions para publicación automatizada:

  • Publicación confiable: Usa la acción de publicación oficial de PyPA con OpenID Connect
  • Activación manual: Se puede activar manualmente con opciones para TestPyPI vs PyPI
  • Respaldo de Twine: Admite tanto publicación confiable como publicación basada en twine

Para configurar la publicación:

  1. Para publicación confiable (recomendado):

    • Configura la publicación confiable en PyPI/TestPyPI con tu repositorio de GitHub
    • No se necesitan secretos: usa OpenID Connect

  2. Para publicación basada en tokens:

    • Añade los secretos PYPI_API_TOKEN y TEST_PYPI_API_TOKEN a tu repositorio
    • Usa la opción "Usar twine" en el despacho del flujo de trabajo

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones de la comunidad! Para comenzar, consulta nuestra guía de contribución para instrucciones de configuración, consejos de desarrollo y pautas.