# justetf-mcp

[![CI](https://github.com/p-gentili/justetf-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/p-gentili/justetf-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)

A local [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for read-only justETF data.

This server wraps the third-party [`druzsan/justetf-scraping`](https://github.com/druzsan/justetf-scraping) Python scraper and exposes a compact MCP tool surface for ETF search, profiles, charts, comparisons, and live quotes.

> Caveat: justETF does not publish a stable public API for these endpoints. The upstream scraper relies on justETF web-app endpoints/page structure, so tools can break if justETF changes its site. Use conservative request volumes and review justETF terms for your use case. This is not investment advice.

## Tools

- `search_etfs` — query the justETF screener with filters and pagination.
- `get_etf_profile` — profile/details for one ISIN, including holdings and country/sector allocations.
- `get_chart` — historical chart/performance series for one ISIN.
- `compare_charts` — compare performance series for multiple ISINs.
- `get_live_quote` — latest gettex/EUR quote via justETF's WebSocket feed.

There is also a `justetf://help` resource with brief usage notes.

## Install

```bash
uv sync
```

Or install as a Python package:

```bash
pip install .
```

## Run locally

```bash
uv run justetf-mcp
```

The server communicates over stdio, which is the usual transport for local MCP clients.

## MCP client configuration

Example configuration for a stdio MCP client:

```json
{
  "mcpServers": {
    "justetf": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/justetf-mcp", "run", "justetf-mcp"]
    }
  }
}
```

If you install the package globally/in a dedicated venv, use the `justetf-mcp` executable directly.

## Example prompts

- "Search justETF for MSCI World accumulating ETFs and show TER and fund size."
- "Get the profile for IE00B4L5Y983 without live quote."
- "Compare IE00B4L5Y983 and IE00B3RBWM25 over the last 5 years."
- "Fetch the last 30 chart rows for IE00B5BMR087."

## Development

```bash
uv sync --dev      # install runtime + dev dependencies
uv run pytest -q   # run the test suite
uv run ruff check . # lint
```

## How the underlying scraper reaches justETF

The upstream `justetf-scraping` package currently uses:

- Screener: `https://www.justetf.com/en/search.html` with Wicket AJAX POST requests.
- Chart data: `https://www.justetf.com/api/etfs/{isin}/performance-chart`.
- Live quote: `wss://api.mobile.stock-data-subscriptions.justetf.com/?subscription=trend&parameters=isins:{isin}/currency:EUR/language:en`.
- Profile pages: `https://www.justetf.com/en/etf-profile.html?isin={isin}` plus AJAX expansion for allocations.

## Acknowledgements

Data access is provided by the third-party
[`druzsan/justetf-scraping`](https://github.com/druzsan/justetf-scraping)
package, which is MIT licensed. This project is not affiliated with or endorsed
by justETF.

## License

[MIT](LICENSE) © Paolo Gentili. The bundled dependency `justetf-scraping` is
also MIT licensed, so the two are license-compatible.