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/) |