# bitflyer-mcp

Read-only [MCP](https://modelcontextprotocol.io) server for **bitFlyer** public market data.
Lets Claude (Desktop / Code) and other MCP clients query bitFlyer's ticker, order book,
recent executions, and exchange health in natural language.

> **Safe by design:** this server uses **only bitFlyer's public REST API** — no API key,
> no authentication, no access to any account, balance, position, or order. It cannot place,
> cancel, or read trades. Worst case for anyone running it is a read of public market data.

> ⚠️ **Not investment advice.** This is an information tool. Trading crypto carries risk.

## Tools

| Tool | What it returns |
|------|-----------------|
| `get_ticker(product_code)` | last price (ltp), best bid/ask, volume, timestamp |
| `get_board(product_code, depth)` | order book summarized to top `depth` levels (mid, spread, bids, asks) |
| `get_executions(product_code, count)` | recent trades (price, size, side, time) |
| `get_board_state(product_code)` | board state (RUNNING / CLOSED / CIRCUIT BREAK, SFD) |
| `get_health(product_code)` | exchange status (NORMAL / BUSY / STOP …) |
| `list_markets()` | all tradable products (spot / FX / futures) |

`product_code` examples: `FX_BTC_JPY` (BTC margin, default), `BTC_JPY` (spot), `ETH_JPY`, `XRP_JPY`.

## Install

```bash
# from PyPI is not published yet — install from source
git clone https://github.com/TakuroidX/bitflyer-mcp.git
cd bitflyer-mcp
pip install -e .
```

Requires Python ≥ 3.10. Dependencies: `mcp`, `httpx`.

## Use with Claude Desktop

Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`):

```json
{
  "mcpServers": {
    "bitflyer": {
      "command": "bitflyer-mcp"
    }
  }
}
```

Then ask Claude things like *"What's the current FX_BTC_JPY price and spread on bitFlyer?"*

## Use with Claude Code

```bash
claude mcp add bitflyer -- bitflyer-mcp
```

## Example

```
> bitFlyer の FX_BTC_JPY、今いくら？板の厚さは？
get_ticker → ltp ¥10,210,000 / best_bid ¥10,209,500 / best_ask ¥10,210,500
get_board  → mid ¥10,210,000 / spread ¥1,000 / 上位10段...
```

## Design notes

- **Public-only / read-only** — the safest possible surface. No credentials are read or stored.
- **Rate-limit aware** — a minimum request interval keeps usage under bitFlyer's public
  per-IP limit (~500 req / 5 min).
- **Board summarization** — the raw board has hundreds of levels; `get_board` returns the
  top-N to stay LLM-context-friendly.
- bitFlyer has **no native OHLC/candle endpoint**, so this server does not fabricate one.

## Development

```bash
pip install -e ".[dev]" pytest pytest-asyncio
pytest
```

## License

MIT © TakuroidX