# mcp-finance-server

Servidor MCP (Model Context Protocol) que expone herramientas de datos financieros usando la API de [Alpha Vantage](https://www.alphavantage.co/). 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

```bash
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](https://www.alphavantage.co/support/#api-key)):

```bash
cp .env.example .env
```

```
ALPHA_VANTAGE_API_KEY=tu-clave-real-aqui
```

### 3. Probarlo localmente (sin cliente MCP)

```bash
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`:

```json
{
  "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:

```python
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__`.