# MCP server

A [Model Context Protocol](https://modelcontextprotocol.io) server at
`https://api.bb.no/mcp` gives an AI assistant read access to a user's account.
Each tool calls an endpoint of this API, takes the fields of that endpoint's
request as its arguments, and returns the same JSON as the endpoint.

## Connecting

The server uses the Streamable HTTP transport. It accepts an access token from
the [OAuth](https://barebitcoin.no/developers/authentication/oauth) authorization code flow in the
`Authorization: Bearer` header. Clients are registered by Bare Bitcoin, with
read scopes only.

A request without a valid token gets `401` with a `WWW-Authenticate` header that
points to the protected resource metadata
([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)) at
`https://api.bb.no/.well-known/oauth-protected-resource/mcp`. The metadata names
the authorization server and the scopes the tools use.

## Tools

A tool needs the same scope as its endpoint, and has the same rate limits.
Market data tools work with any token. List tools return 50 items per page when
no page size is given.

A failed call returns a tool result with `isError` set and the API's error
message as its text.

### `price`

Fetch BTCNOK. Calls [BTC/NOK prices](https://barebitcoin.no/developers/api/market-data/price). Works with any token.

Fetches the current BTCNOK price at Bare Bitcoin: the mid price, bid, ask, and the buy and sell prices for card and bank payments.

| Argument | Type | Description |
| --- | --- | --- |
| `amount` | number | Amount NOK to trade for. If empty, defaults to 5000 NOK. |

### `volume`

Fetch volume statistics. Calls [Volume statistics](https://barebitcoin.no/developers/api/market-data/volume). Works with any token.

Returns statistics about the volume of BTCNOK trades at Bare Bitcoin: the last 24 hours, 7, 30 and 365 days, all time, and the day, month and year of a date.

| Argument | Type | Description |
| --- | --- | --- |
| `date` | string | The date to fetch the volume for. If empty, defaults to today. Format: YYYY-MM-DD |

### `list_bitcoin_accounts`

Fetch bitcoin accounts. Calls [List bitcoin accounts](https://barebitcoin.no/developers/api/accounts/bitcoin-accounts). Scope: `api:accounts:bitcoin:read`.

Lists the bitcoin accounts for the user. Each bitcoin account has a separate balance. Every bitcoin transaction (withdrawal, deposit, trade, bonus payout) affects the balance of exactly one bitcoin account.

| Argument | Type | Description |
| --- | --- | --- |
| `includeDeleted` | boolean | Include accounts that have previously been deleted. |

### `list_trades`

List trades. Calls [List trades](https://barebitcoin.no/developers/api/orders/trades). Scope: `api:trades:read`.

Lists the user's executed trades, newest first. When hasMore is true, pass nextBefore and nextBeforeId as before and beforeId to fetch the next page.

| Argument | Type | Description |
| --- | --- | --- |
| `pageSize` | integer | Items per page (max 200). When set to 0, all matching trades are returned, except through MCP, where it defaults to 50. Default: 50 |
| `before` | string · date-time | Trades are listed newest first, so pagination walks backward in time. Only return trades created before this time. Can be used standalone to filter down to an end date; pass next_before from the previous response (together with next_before_id) to fetch the next page. |
| `beforeId` | string | Pagination cursor tiebreaker: when multiple trades share the same create_time, this ID breaks the tie. Pass next_before_id from the previous response. Requires 'before'; supplying 'before_id' alone is rejected. |

### `get_lightning_invoice`

Fetch a Lightning invoice. Calls [Get Lightning invoice](https://barebitcoin.no/developers/api/transfers/get-lightning-invoice). Scope: `api:deposits:lightning:read`.

Fetches a Lightning invoice the user created, and whether it is paid.

| Argument | Type | Description |
| --- | --- | --- |
| `id` (required) | string | Can be: 1. Deposit destination ID. Prefix: `ded_`. 2. The Lightning invoice itself. |

### `list_tax_transactions`

List tax transactions. Calls [Tax transactions](https://barebitcoin.no/developers/api/tax/transactions). Scope: `api:tax:transactions:read`.

Lists tax-relevant transactions done by the user within the Bare Bitcoin platform, oldest first: trades, bitcoin deposits and withdrawals, NOK deposits and withdrawals, bonuses and adjustments. Note that this does NOT include any of the third party transactions imported into the platform tax calculator. When hasMore is true, pass nextAfter and nextAfterId as after and afterId to fetch the next page.

| Argument | Type | Description |
| --- | --- | --- |
| `pageSize` | integer | Items per page (max 200). When set to 0, all matching transactions are returned, except through MCP, where it defaults to 50. Default: 50 |
| `after` | string · date-time | Transactions are listed oldest first (required to compute running_balance_btc correctly), so pagination walks forward in time. Only return transactions created after this time. Can be used standalone to filter down to a start date; pass next_after from the previous response (together with next_after_id) to fetch the next page. |
| `afterId` | string | Pagination cursor tiebreaker: when multiple transactions share the same create_time, this ID breaks the tie. Pass next_after_id from the previous response. Requires 'after'; supplying 'after_id' alone is rejected. |
| `before` | string · date-time | Only return transactions created strictly before this time. Filter only, does not affect pagination direction. |

### `get_tax_balance`

Fetch balances. Calls [Tax balances](https://barebitcoin.no/developers/api/tax/balances). Scope: `api:accounts:bitcoin:read`.

Fetches the user's current balances: the NOK balance, and the balance of each bitcoin account.

| Argument | Type | Description |
| --- | --- | --- |
| `includeDeleted` | boolean | Include accounts that have previously been deleted. Useful for resolving the name of an account referenced by an older transaction. |


Source: https://barebitcoin.no/developers/mcp
