# bvb-mcp

Read-only MCP server for the **Bucharest Stock Exchange** (Bursa de Valori
București, BVB). It exposes BVB's own public backend — the TradingView-UDF
datafeed at `wapi.bvb.ro` and the market-list pages at `www.bvb.ro` — as MCP
tools: instrument universe, symbol search and metadata, and OHLCV candles.

No account, no API key, no token: the BVB backend is public and unauthenticated.
Every tool is read-only; there is nothing to trade through here.

## Features

- OHLCV candles for any BVB ticker or index (`get_candles`), with a clean
  `resolution` parameter that hides the datafeed's `1D`-not-`D` quirk.
- Full instrument universe scraped from the exchange's market-list pages
  (`list_instruments`) — ticker + ISIN + name — plus the index universe
  (`list_indices`).
- Datafeed symbol search (`search_symbol`) and per-symbol metadata
  (`get_symbol_info`), with diagnostics (`server_time`, `datafeed_config`).
- Browser-like `User-Agent` and `Referer: https://www.bvb.ro/` on every request
  (defensive; no cookies, no token).
- One automatic retry on HTTP 429, honouring `Retry-After` (capped at 30s).
- stdio transport by default, HTTP (`/mcp`) on request.

## Tools

All tools are read-only (there are no write tools):

| Tool | Description |
|---|---|
| `list_instruments` | List a market's instrument universe (ticker + ISIN + name) by scraping the BVB market-list page. Markets: `shares`, `bonds`, `fund-units` (ETFs), `warrants`, `certificates` (`structured`) |
| `list_indices` | List the BVB index universe (BET, BET-TR, BET-FI, ROTX, …) |
| `search_symbol` | Datafeed symbol search by ticker/name (server-capped at ~30 results) |
| `get_symbol_info` | Resolve a ticker to its metadata: name, type, session, timezone, currency, sector/industry |
| `get_candles` | OHLCV candles for a ticker/index at minute/daily/weekly/monthly resolution |
| `get_fundamentals` | Company details + valuation snapshot scraped from the detail page: identity, Indicatori bursieri (market cap, P/E, P/BV, EPS, div yield, dividend), issue info, and ownership structure |
| `financial_summary` | One-call bundle for a fundamental ("Buffett-style") analysis: `get_fundamentals` + a price summary (last close, 52-week range, 1y/5y change). Returns data, not a verdict |
| `server_time` | Datafeed server time (reachability check) |
| `datafeed_config` | Datafeed configuration: instrument-type codes and supported resolutions |

### Notes on the data surface

- **Search is capped.** `search_symbol` mirrors the datafeed's own search,
  which returns roughly 30 results for broad queries. Use `list_instruments`
  (or `list_indices`) to enumerate the full universe.
- **The `1D` quirk.** The datafeed advertises a bare `D` for daily bars but the
  history endpoint only accepts `1D` (bare `D` returns HTTP 500). `get_candles`
  takes a friendly `resolution` (`1`, `5`, `15`, `30`, `60`, `1D`, `1W`, `1M`;
  `D`/`W`/`M` are accepted too) and sends the correct code.
- **Index metadata is partial.** `list_indices` always returns every index's
  `symbol`, but `name`/`isin` are populated only for the indices BVB renders a
  server-side profile card for; the rest load via client-side tabs and come
  back as `null`.
- **Rights / structured.** BVB publishes no standalone "rights" market page, and
  "structured products" (datafeed type `T`) are split across the `warrants` and
  `certificates` pages — `structured` is accepted as an alias for
  `certificates`.
- **No multi-year statements.** `get_fundamentals` / `financial_summary` expose
  BVB's current snapshot (valuation ratios, dividend, ownership) — BVB does not
  publish structured multi-year income/balance/cash-flow statements, so a full
  10-year ROE/margin/FCF track record is not available. Pair with `get_candles`
  for the price trend; the client (LLM) does the analysis.

## Configuration

All configuration is via environment variables, and all of it is optional — the
BVB backend needs no credentials.

| Variable | Default | Purpose |
|---|---|---|
| `BVB_DATAFEED_URL` | `https://wapi.bvb.ro` | Datafeed base URL |
| `BVB_WEB_URL` | `https://www.bvb.ro` | Market-list site base URL |
| `BVB_MCP_USER_AGENT` | a Chrome-like UA | `User-Agent` sent on every request |
| `BVB_LANG` | `ro` | Language for the datafeed config endpoint |

## Getting started

Run straight from the repository with [uv](https://docs.astral.sh/uv/):

```bash
uvx --from git+https://github.com/florinel-chis/bvb-mcp bvb-mcp
```

The server speaks stdio by default; add `--transport http --port 8000` to serve
MCP over HTTP at `/mcp` instead. HTTP binds `127.0.0.1` by default, and a
non-loopback `--host` is refused unless `--allow-remote` is also passed — read
the [Safety](#safety) section before using that flag.

## MCP client configuration

Add the server to your MCP client's configuration (stdio, via `uvx`):

```json
{
  "mcpServers": {
    "bvb": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/florinel-chis/bvb-mcp", "bvb-mcp"]
    }
  }
}
```

Or run the Docker image (build it first, see below):

```json
{
  "mcpServers": {
    "bvb": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "bvb-mcp"]
    }
  }
}
```

## Docker

A small (~200 MB) multi-stage image that works both ways an MCP client might use
it — spawned per call over **stdio**, or as a long-running **HTTP** server. Both
paths are verified against BVB's live backend. The container only needs outbound
network to reach `wapi.bvb.ro` / `www.bvb.ro`; no credentials or volumes.

**Build:**

```bash
docker build -t bvb-mcp .
```

**stdio** — what an MCP client spawns (use `bvb-mcp` as the image name in the
docker config above):

```bash
docker run -i --rm bvb-mcp
```

**HTTP** — a shared, long-running server at `http://127.0.0.1:8000/mcp/`:

```bash
docker run --rm -p 127.0.0.1:8000:8000 bvb-mcp \
  --transport http --host 0.0.0.0 --port 8000 --allow-remote
```

`--host 0.0.0.0` binds inside the container so the port mapping works — which is
why `--allow-remote` is needed; the `127.0.0.1:` prefix on `-p` keeps the
endpoint reachable from this machine only (it is unauthenticated — see Safety).
If host port 8000 is taken, map another, e.g. `-p 127.0.0.1:8010:8000`.

**Share without a registry** — hand the image to someone as a file they
`docker load`, no Docker Hub / GHCR needed:

```bash
docker save bvb-mcp:latest | gzip > bvb-mcp.tar.gz   # you: export
docker load < bvb-mcp.tar.gz                          # them: image is now local
```

## Safety

- The HTTP transport has **no authentication**: anyone who can reach the `/mcp`
  endpoint can call every tool. Keep it bound to `127.0.0.1` (the CLI default;
  with Docker, publish as `-p 127.0.0.1:8000:8000`) or put it behind an
  authenticating reverse proxy. Never expose it directly on a public network.
- All tools are read-only — this server cannot place orders or move money.
- Use at your own risk. Nothing here is investment advice.

## Data & terms

This server ships **code, not data**. It fetches from BVB's own public backend
at request time and returns whatever BVB serves. Redistributing or otherwise
using BVB price data is subject to BVB's terms and any applicable market-data
licensing, and is **your responsibility** as the operator — the software makes
no representation about your right to store, redistribute, or trade on the data
it relays.

## Development

```bash
uv sync
uv run pytest -q
uv run ruff check .
```

Tests are fully offline: HTTP is stubbed with `respx` against captured BVB
response fixtures in `tests/fixtures/`.

## License

MIT