Alpha Vantage

Acesse dados do mercado de ações em tempo real e históricos da API Alpha Vantage.

GitHub
75
Experimente este MCPPatrocinado

Documentação

✅ Servidor MCP Oficial Alpha Vantage

smithery badge Verified on MseeP

Um servidor MCP para a API de dados do mercado de ações, API Alphavantage.

Alpha Vantage Server MCP server

URL do Servidor MCP: https://mcp.alphavantage.co

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

Configuração

Obtendo uma Chave de API

  1. Cadastre-se para obter uma chave gratuita da API Alphavantage
  2. Adicione a chave da API às suas variáveis de ambiente como ALPHAVANTAGE_API_KEY

Instalação

Opção 1: Usando uvx (Recomendado)

A maneira mais fácil de usar o servidor MCP AlphaVantage é com uvx:

# Run directly without installation
uvx alphavantage-mcp

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

Opção 2: Usando pip

pip install alphavantage-mcp
alphavantage-mcp

Opção 3: A partir do código-fonte

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

Modos do Servidor

O servidor AlphaVantage pode ser executado em dois modos diferentes:

Servidor Stdio (Padrão)

Este é o modo padrão do servidor MCP usado para ferramentas como o Claude Desktop.

alphavantage
# or explicitly:
alphavantage --server stdio

Servidor HTTP Streamable

Este modo fornece atualizações em tempo real via streaming HTTP.

alphavantage --server http --port 8080

Servidor HTTP Streamable com Autenticação OAuth 2.1

Este modo adiciona autenticação OAuth 2.1 ao servidor HTTP, seguindo a especificação MCP para acesso seguro.

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

Configuração OAuth

Ao usar o sinalizador --oauth, o servidor exige configuração OAuth 2.1 por meio de variáveis de ambiente:

Variáveis de Ambiente Obrigatórias:

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

Variáveis de Ambiente Opcionais:

# 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"

Recursos OAuth

A implementação OAuth fornece:

  • Endpoint de Metadados de Recurso Protegido OAuth 2.0 (/.well-known/oauth-protected-resource)
  • Autenticação por token Bearer para todas as solicitações MCP
  • Métodos de validação JWT e Introspecção de Token
  • Conformidade com as Melhores Práticas de Segurança MCP:
    • Validação de público-alvo do token (previne ataques de passagem de token)
    • Prevenção de sequestro de sessão com IDs de sessão seguros
    • Sessões vinculadas ao usuário para segurança adicional
    • Cabeçalhos WWW-Authenticate adequados para respostas 401

Exemplo: Configuração Keycloak

Para testes com 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

Fluxo do Cliente OAuth

Quando o OAuth está habilitado, os clientes MCP devem:

  1. Descobrir o servidor de autorização via GET /.well-known/oauth-protected-resource
  2. Registrar-se no servidor de autorização (se estiver usando Registro Dinâmico de Clientes)
  3. Obter tokens de acesso do servidor de autorização
  4. Incluir tokens nas solicitações: Authorization: Bearer <access-token>
  5. Tratar respostas 401/403 e renovar tokens conforme necessário

Opções:

  • --server: Escolha entre o modo de servidor stdio (padrão) ou http
  • --port: Especifique a porta para o servidor HTTP Streamable (padrão: 8080)
  • --oauth: Habilite a autenticação OAuth 2.1 (requer --server http)

📊 Telemetria

O servidor MCP AlphaVantage inclui métricas Prometheus opcionais para monitoramento e observabilidade.

Habilitando Telemetria

Defina as seguintes variáveis de ambiente para habilitar a telemetria:

# 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

Quando a telemetria está habilitada, as métricas Prometheus estão disponíveis em:

http://localhost:9464/metrics

Métricas Disponíveis

O servidor coleta as seguintes métricas para cada chamada de ferramenta:

  • mcp_tool_calls_total - Número total de chamadas de ferramentas (rotuladas por ferramenta e resultado)
  • mcp_tool_latency_seconds - Histograma de latência de execução de ferramentas
  • mcp_tool_request_bytes - Histograma de tamanho do payload da solicitação
  • mcp_tool_response_bytes - Histograma de tamanho do payload da resposta
  • mcp_tool_active_concurrency - Medidor de chamadas de ferramentas simultâneas ativas
  • mcp_tool_errors_total - Total de erros por tipo (timeout, bad_input, connection, unknown)

Exemplo de Uso com Telemetria

# 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

🚀 Implantação Serverless na AWS

Implante o Servidor MCP AlphaVantage no AWS Lambda usando o padrão MCP sem estado para implantação escalável e pronta para produção.

Implantação Rápida na AWS

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

Recursos:

  • ✅ Padrão MCP sem estado - Perfeito para o modelo de execução do Lambda
  • ✅ Escala automática - Lida com qualquer carga com AWS Lambda + API Gateway
  • ✅ Custo-benefício - Pague apenas pelas solicitações (~US$ 1-5/mês para uso típico)
  • ✅ Pronto para produção - Baseado nos padrões oficiais de exemplo da AWS
  • ✅ Suporte OAuth 2.1 - Autenticação opcional para acesso seguro

📖 Documentação Completa: Consulte o Guia de Implantação na AWS para instruções completas de configuração, testes, monitoramento e solução de problemas.

Uso com Claude Desktop

Opção 1: Usando uvx (Recomendado)

Adicione isto ao seu claude_desktop_config.json:

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

Opção 2: A partir do código-fonte

Se você clonou o repositório, use esta configuração:

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

Executando o Servidor no Modo HTTP Streamable

Usando uvx:

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

A partir do código-fonte:

{
  "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"
      }
    }
  }
}

📺 Vídeo de Demonstração

Assista a uma demonstração rápida do Servidor MCP Alpha Vantage em ação:

Alpha Vantage MCP Server Demo

🔧 Desenvolvimento e Publicação

Publicação no PyPI

Este projeto inclui scripts para publicação no PyPI e 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

O script usa twine por padrão (recomendado), mas também pode usar uv publish com o sinalizador --use-uv.

GitHub Actions

O repositório inclui um fluxo de trabalho GitHub Actions para publicação automatizada:

  • Publicação Confiável: Usa a ação oficial de publicação do PyPA com OpenID Connect
  • Acionamento Manual: Pode ser acionado manualmente com opções para TestPyPI vs PyPI
  • Fallback Twine: Suporta tanto publicação confiável quanto publicação baseada em twine

Para configurar a publicação:

  1. Para Publicação Confiável (recomendado):

    • Configure a publicação confiável no PyPI/TestPyPI com seu repositório GitHub
    • Nenhum segredo necessário - usa OpenID Connect

  2. Para Publicação Baseada em Token:

    • Adicione os segredos PYPI_API_TOKEN e TEST_PYPI_API_TOKEN ao seu repositório
    • Use a opção "Usar twine" no acionamento do fluxo de trabalho

🤝 Contribuindo

Aceitamos contribuições da comunidade! Para começar, consulte nosso guia de contribuição para instruções de configuração, dicas de desenvolvimento e diretrizes.