mcp-finance-server

Servidor MCP (Model Context Protocol) que expone herramientas de datos financieros usando la API de Alpha Vantage. Permite que Claude Desktop u otros clientes MCP consulten cotizaciones bursátiles y datos de empresas directamente en una conversación natural, sin salir del chat.

Qué es MCP

Model Context Protocol (MCP) es un estándar abierto que permite conectar modelos de lenguaje como Claude con herramientas y fuentes de datos externas de forma estructurada. Un servidor MCP expone un conjunto de "herramientas" (funciones) que el cliente (por ejemplo, Claude Desktop) puede invocar durante la conversación, pasándole argumentos y recibiendo resultados de vuelta. Esto evita tener que copiar y pegar datos manualmente: el modelo decide cuándo llamar a la herramienta según lo que el usuario le pida.

Herramientas expuestas

obtener_precio_actual(ticker: str)

Consulta el endpoint GLOBAL_QUOTE de Alpha Vantage y devuelve el precio actual, la variación y el porcentaje de cambio de un ticker.

Ejemplo de uso (en una conversación con Claude Desktop):

Usuario: ¿A cuánto cotiza AAPL ahora mismo?

Claude (llama a obtener_precio_actual("AAPL")):

Cotización de AAPL:
Precio actual: 311.0000 USD
Variación: 1.6200
Cambio porcentual: 0.5236%

obtener_resumen_empresa(ticker: str)

Consulta el endpoint OVERVIEW de Alpha Vantage y devuelve nombre, sector, industria, capitalización de mercado y una breve descripción de la empresa.

Ejemplo de uso:

Usuario: Dame un resumen de la empresa detrás del ticker MSFT.

Claude (llama a obtener_resumen_empresa("MSFT")):

Resumen de Microsoft Corporation (MSFT):
Sector: TECHNOLOGY
Industria: SERVICES-PREPACKAGED SOFTWARE
Capitalización de mercado: 3120000000000
Descripción: Microsoft Corporation is an American multinational technology company...

Cómo instalarlo y conectarlo

1. Instalar dependencias

cd mcp-finance-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Configurar la API key

Copia .env.example a .env y añade tu clave de Alpha Vantage (gratuita en alphavantage.co/support/#api-key):

cp .env.example .env

ALPHA_VANTAGE_API_KEY=tu-clave-real-aqui

3. Probarlo localmente (sin cliente MCP)

python main.py test AAPL

Esto ejecuta ambas herramientas directamente y muestra el resultado por consola, útil para verificar que la key funciona antes de conectar un cliente.

4. Añadirlo a Claude Desktop

Edita el archivo de configuración de Claude Desktop (claude_desktop_config.json) y añade el servidor dentro de mcpServers, usando la ruta absoluta al Python del entorno virtual y al main.py:

{
  "mcpServers": {
    "finance-server": {
      "command": "/ruta/absoluta/a/mcp-finance-server/venv/bin/python",
      "args": [
        "/ruta/absoluta/a/mcp-finance-server/main.py"
      ]
    }
  }
}

Reinicia Claude Desktop tras guardar el archivo. Las herramientas obtener_precio_actual y obtener_resumen_empresa aparecerán disponibles en la conversación.

Limitaciones

• El plan gratuito de Alpha Vantage limita las peticiones a 25 al día (y 1 por segundo). Al superarlo, la API no devuelve un error HTTP, sino un JSON 200 OK con una clave Note o Information explicando el límite.
• Ambas herramientas detectan estas respuestas (Error Message, Note, Information) y devuelven un mensaje legible en vez de fallar o devolver un JSON crudo, para que el cliente MCP pueda mostrárselo al usuario de forma clara.
• No hay caché ni reintentos automáticos: cada llamada consume una petición de la cuota diaria.

Qué aprendí

Al probar el servidor conectado desde Claude Desktop (en vez del modo test local), config.py fallaba al no encontrar la variable ALPHA_VANTAGE_API_KEY pese a que el .env existía en la carpeta del proyecto. La causa: load_dotenv() sin argumentos busca el archivo .env en el directorio de trabajo actual del proceso, no en la carpeta donde vive el script. Claude Desktop lanza el proceso con su propio directorio de trabajo (no el del proyecto), así que la búsqueda relativa fallaba silenciosamente.

La solución fue anclar la ruta del .env a la ubicación del propio archivo config.py, independientemente de desde dónde se invoque el script:

from pathlib import Path
from dotenv import load_dotenv

load_dotenv(Path(__file__).parent / ".env")

Lección general: cualquier script pensado para ser lanzado por un proceso externo (un cliente MCP, un cron, un servicio) no debe asumir nada sobre el directorio de trabajo actual — todas las rutas a archivos propios del proyecto deben resolverse de forma absoluta a partir de __file__.