bitvavo-mcp

An MCP server that exposes a Bitvavo crypto exchange account as read-only tools for Claude (and other MCP clients).

⚠️ Read-only by design. The server only calls Bitvavo endpoints that view information — no trading, no withdrawals. Create your API key with the View information scope only.

What it does

Once connected, Claude can answer questions like:

• "What is my portfolio worth right now?"
• "How much XRP do I hold and what's my average cost basis?"
• "Show me my trade history on BTC-EUR."
• "What were my last 5 deposits and withdrawals?"

Tools

Tool	Purpose
ping	Verify the connection and credentials, return server time + fee tier
get_balance	List per-asset balances (available + in-order)
get_portfolio_value	Total portfolio value in EUR with breakdown
get_ticker	24-hour ticker for one market
get_markets	List tradable markets, filterable by quote / status
get_trades	Your filled trades on a specific market
get_deposits	Deposit history, optionally filtered by asset
get_withdrawals	Withdrawal history, optionally filtered by asset
get_open_orders	Orders that are placed but not yet filled
get_pnl	Average-cost P&L per position, with cost basis + unrealized/realized split
import_transactions	Import a Bitvavo CSV transaction export into a local SQLite store
get_transactions	Query the locally-stored transaction history
get_candles	Historical OHLCV candles for a market (any interval from 1m to 1d)
get_trend	Multi-period trend digest — 24h/7d/30d/90d/1y % changes plus your cost-basis comparison

Install

You need Node.js 18 or later and a Bitvavo API key + secret with View information scope (create one).

Claude Desktop

Open your Claude Desktop config file:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Add an entry under mcpServers:

{
  "mcpServers": {
    "bitvavo": {
      "command": "npx",
      "args": ["-y", "bitvavo-mcp"],
      "env": {
        "BITVAVO_API_KEY": "your_api_key",
        "BITVAVO_API_SECRET": "your_api_secret"
      }
    }
  }
}

Restart Claude Desktop. The Bitvavo tools appear in the tools menu (hammer icon) of any new chat. npx -y downloads the latest published version on first run and caches it locally — no manual install step.

Claude Code

claude mcp add --scope user bitvavo \
  -e BITVAVO_API_KEY=your_api_key \
  -e BITVAVO_API_SECRET=your_api_secret \
  -- npx -y bitvavo-mcp

Use --scope local if you only want it active in the current project directory.

From source

If you want to hack on the code:

git clone https://github.com/aderik/bitvavo-mcp.git
cd bitvavo-mcp
npm install
npm run build
cp .env.example .env  # then fill in BITVAVO_API_KEY and BITVAVO_API_SECRET

Point Claude Desktop at the built file instead of npx:

{
  "mcpServers": {
    "bitvavo": {
      "command": "node",
      "args": ["/absolute/path/to/bitvavo-mcp/dist/server.js"]
    }
  }
}

The .env file is loaded relative to the running script, so credentials are found regardless of which directory Claude spawns the server from. .env is gitignored — never commit it.

Full transaction history via CSV import

Bitvavo's /trades and /orders REST endpoints expose only exchange (Advanced) trades. Transactions made via the Buy/Sell or Convert UI in the Bitvavo app use a separate brokerage backend and do not appear in the API. Staking distributions and rebates aren't in the API either.

To get the complete picture:

1. Download your transaction CSV from Bitvavo: Account → Transactiegeschiedenis → Exporteren → Volledige geschiedenis → format CSV.
2. In your Claude chat: "import_transactions van /pad/naar/Volledige geschiedenis.csv" — or call the tool directly.
3. Run get_pnl again — every traded asset (including fully sold-off positions) now shows its realized P&L, sourced from the imported records.

The data lives in ~/.bitvavo-mcp/transactions.db (override with BITVAVO_MCP_DATA_DIR=/some/path). Re-importing the same CSV is idempotent — rows are matched on Bitvavo's transaction_id.

Environment variables

Variable	Required	Purpose
BITVAVO_API_KEY	yes	API key from https://account.bitvavo.com/user/api
BITVAVO_API_SECRET	yes	The matching secret
BITVAVO_MCP_DATA_DIR	no	Override the SQLite location (default ~/.bitvavo-mcp/)