Skip to main content
Glama
bolesk

crypto-transactions-mcp

by bolesk

crypto-transactions-mcp

MCP server for tracking transactions and orders executed in the crypto market. It exposes MCP tools that let an LLM agent (Claude, agy, etc.) record trades, swaps, and transfers with exact Decimal precision, and query the history — with swappable persistence on a local JSON file or a Notion database.

Quick Start

  1. uv sync to install dependencies.

  2. Choose a backend:

  3. Add the server to your MCP host configuration: see "Claude Desktop configuration" or "agy configuration".

  4. Restart the host and try, for example: "I bought 0.1 BTC on Binance at 65000 USDT, fee 0.0001 BTC, record it with log_transaction."

Onion architecture:

  • domain/ — the CryptoTransaction entity (Pydantic v2, monetary fields in Decimal). side is BUY/SELL (trade, including a crypto/crypto swap) or TRANSFER (moving the same asset between two custodial accounts); the two cases have different requirements validated in the model itself (BUY/SELL require price/value, TRANSFER requires to_exchange)

  • interfaces/ — the TransactionRepository and TransactionFilters ports

  • usecases/LogTransactionUseCase (trade, upsert with partial merge), LogTransferUseCase (transfer, same upsert semantics), GetTransactionHistoryUseCase

  • infrastructure/ — concrete adapters of the TransactionRepository port:

    • JsonTransactionRepository, local JSON file, fixed path data/crypto_transactions.json

    • NotionTransactionRepository, Notion database (see below)

  • delivery/ — the FastMCP server, MCP tools (log_transaction, log_transfer, get_transaction_history), dependency wiring in factories.py

Related MCP server: Expense Tracker MCP Server

MCP tools

  • log_transaction — BUY/SELL trade, including a swap between two cryptos (e.g. ETH/BTC): same shape as a normal trade, no separate tool needed. Supports optional fiat_value/fiat_currency to lock in the fiat equivalent at the time of the exchange — strongly recommended for crypto/crypto swaps, where price alone (the relative exchange rate between the two cryptos) does not allow you to calculate the realized P&L afterwards, nor the fiat cost basis of the new asset received.

  • log_transfer — moving the same asset between two custodial accounts (exchangeto_exchange), not a trade: no side/price, but requires to_exchange.

  • get_transaction_history — history of both, with optional filters (symbol, exchange, side including "TRANSFER", date_from/date_to), sorted by date descending (most recent first) and paginated (limit default 50, offset); the response is {"transactions": [...], "has_more": bool}.

  • get_portfolio_summary — for each asset (excluding vs_currency itself): how much you own, how much you invested in total and on average per unit (cost basis), market value, unrealized gain/loss. Optional as_of_date for a position as of a past date (historical price) instead of live — designed for tax reporting. cost_basis_method (weighted_average or fifo) is an explicit choice, not automatic: they can produce different capital gains on the same history, check with an accountant which one you need.

  • get_asset_price — quote for a single asset, current or historical as of a date, without computing the whole portfolio.

Setup

uv sync

Copy .env.example to .env and fill it in: it is loaded automatically at startup (main.py calls load_dotenv()). This works even when the server is launched by an external host (Claude Desktop, agy, ...) with uv run --directory <path> main.py, because --directory sets the process working directory to the project root, where load_dotenv() looks for .env by default — there is no need to duplicate secrets in the host config JSON, which is often less protected than a local gitignored .env.

Persistence backend

Selectable with the TRANSACTION_REPOSITORY_BACKEND environment variable:

  • json (default) — no additional configuration required.

  • notion — requires NOTION_TOKEN (Notion integration token) and NOTION_DATABASE_ID.

Set up Notion from scratch

If you don't already have a Notion integration connected to this project, follow these steps in order (requires a Notion account with permission to create integrations in the workspace):

  1. Create the integration — go to notion.so/my-integrations → "+ New integration" → give it a name (e.g. "Crypto Transactions MCP") → choose the workspace → type "Internal".

  2. Enable the capabilities — on the integration configuration page, under "Capabilities", enable: Read content, Update content, Insert content.

  3. Copy the token — "Secrets" tab → copy the value of "Internal Integration Secret" (starts with secret_ or ntn_). This is your NOTION_TOKEN.

  4. Create the database — in Notion, create a new database (full-page or inline) and configure it with exactly the properties listed in the table below. The "title" column that Notion creates by default (usually "Name") must be renamed to Transaction ID: every Notion database is required to have one; it is not the database name but the column that identifies each row.

  5. Share the database with the integration — open the database page → "..." menu at the top right → "Connections" → search for and connect the integration created in step 1. Without this step the API returns 404 even with a valid token, because Notion permissions are per-page, not workspace-wide.

  6. Find the database ID — it is in the database page URL: https://www.notion.so/<ID-senza-trattini>?v=.... For example, from https://www.notion.so/abcdef0123456789abcdef0123456789?v=... the ID is abcdef0123456789abcdef0123456789. This is your NOTION_DATABASE_ID.

  7. Configure the variables — in your .env (see above), or in the host MCP env block:

    TRANSACTION_REPOSITORY_BACKEND=notion
    NOTION_TOKEN=<il secret del punto 3>
    NOTION_DATABASE_ID=<l'id del punto 6>

The Notion database must have these properties (exact name and type):

Property

Type

Transaction ID

title

Tx Hash

rich_text

Exchange

select

To Exchange

select

Symbol

select

Side

select (BUY, SELL, TRANSFER)

Timestamp

date (with time, UTC)

Amount

number

Price

number

Value

number

Fee Amount

number

Fee Asset

select

Fiat Value

number

Fiat Currency

select

Notes

rich_text

To Exchange, Price, Value, Fiat Value, Fiat Currency can be empty (they don't apply to a TRANSFER, or they are optional on a trade).

Note: numeric fields on Notion are native number (float64), not exact Decimal like in the JSON backend — sufficient for real trading amounts, but subject to the precision limits of a double-precision float.

Tests

uv run pytest

Manual execution

uv run main.py

Claude Desktop configuration

Add to the claude_desktop_config.json file (on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json). With an .env already configured at the project root (see above), that's all you need, no secrets in the JSON:

{
  "mcpServers": {
    "crypto-transactions": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/crypto-transactions-mcp",
        "main.py"
      ]
    }
  }
}

Alternatively, if you prefer not to use a .env file, you can pass the variables directly in the env block (they override those in .env if both are present):

{
  "mcpServers": {
    "crypto-transactions": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/crypto-transactions-mcp",
        "main.py"
      ],
      "env": {
        "TRANSACTION_REPOSITORY_BACKEND": "notion",
        "NOTION_TOKEN": "secret_...",
        "NOTION_DATABASE_ID": "abcdef0123456789abcdef0123456789"
      }
    }
  }
}

agy configuration

Same mcpServers schema, but in the .agents/mcp_config.json file at the project root where you use agy (add the crypto-transactions entry next to the other servers already present, without removing them). The same applies: with .env configured you don't need the env block:

{
  "mcpServers": {
    "crypto-transactions": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/crypto-transactions-mcp",
        "main.py"
      ]
    }
  }
}

Available Tools

3 tools
get_transaction_historyA

Restituisce lo storico delle transazioni salvate (trade e transfer), filtrato opzionalmente per symbol, exchange, side (usa "TRANSFER" per i soli transfer) e/o intervallo di date (date_from/date_to, inclusivi, in UTC).

ParametersJSON Schema
NameRequiredDescriptionDefault
sideNo
symbolNo
date_toNo
exchangeNo
date_fromNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the action is read-only ('Restituisce') and specifies that date filters are inclusive and in UTC. However, it does not disclose other behavioral traits such as response format, pagination, or any side effects. The description is minimally adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the main action and then details parameters. It is concise but could be restructured for easier scanning (e.g., bullet points). However, it contains no unnecessary words and effectively communicates the tool's purpose and filters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists (assumed but not shown), so explanation of return values is not required. The description covers filtering options and date inclusivity/UTC zone. However, it lacks information on default behavior (e.g., returns all history if no filters), pagination, or response limits. For a history retrieval tool, this is acceptable but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description adds meaningful context: it explains the side parameter can use 'TRANSFER' to filter only transfers, and notes that date filters are inclusive and in UTC. This adds semantic value beyond the schema's property names and types. It could further describe parameter formats or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns saved transaction history (trades and transfers) with optional filtering. The verb 'Restituisce' and resource 'storico delle transazioni' are specific. Sibling tools (log_transaction, log_transfer) are for creation, so the read purpose is distinguishable, though not explicitly contrasted.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage: use when you need to retrieve transaction history. The description lists available filters but does not provide explicit guidance on when to use this tool versus siblings or when not to use it. No alternatives or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

log_transactionA

Registra un trade (BUY/SELL, incluso uno swap tra due crypto), upsert per id.

    Trade normale (es. BTC/USDT): symbol è la coppia BASE/QUOTE,
    side=BUY se acquisti il base, side=SELL se lo cedi; price è il
    prezzo unitario del base in quote.

    Swap crypto/crypto (es. scambio ETH -> BTC su un DEX o un exchange):
    si usa questo stesso tool, non ce n'è uno dedicato. Metti come base
    l'asset ceduto e come quote quello ricevuto, es. symbol="ETH/BTC",
    side="SELL", amount=1 (ETH ceduti), price=0.05 (BTC ricevuti per
    ETH). Attenzione: in questo caso price ti dice solo il cambio tra
    le due crypto, non il loro controvalore in una valuta fiat — senza
    quel dato non potrai più calcolare a posteriori né il P&L realizzato
    sull'asset ceduto né il cost-basis fiat del nuovo asset ricevuto.
    Per questo, quando disponibile, valorizza sempre fiat_value (il
    controvalore totale dello scambio, es. in EUR al momento
    dell'esecuzione) e fiat_currency: è fortemente consigliato per gli
    swap crypto/crypto, utile anche per i trade con quote fiat/stablecoin.

    Se `id` è omesso viene generata una nuova transazione con un id
    generato automaticamente. Se `id` corrisponde a una transazione già
    salvata, solo i campi passati vengono aggiornati (merge parziale);
    `value` viene ricalcolato come amount * price se non fornito
    esplicitamente e uno tra amount/price cambia. Per una nuova
    transazione sono richiesti tutti i campi obbligatori dello schema
    (exchange, symbol, side, timestamp, amount, price, fee_amount,
    fee_asset). `tx_hash` è opzionale, usalo per l'hash on-chain quando
    disponibile (tipico per gli swap su DEX).

    Per spostare lo stesso asset tra due exchange/wallet, senza
    scambiarlo con un altro asset, usa invece il tool log_transfer.
    
ParametersJSON Schema
NameRequiredDescriptionDefault
idNo
sideNo
notesNo
priceNo
valueNo
amountNo
symbolNo
tx_hashNo
exchangeNo
fee_assetNo
timestampNo
fee_amountNo
fiat_valueNo
fiat_currencyNo

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses key behavioral traits: upsert behavior (merge partial update when id matches), auto-generation of id for new transactions, recalculation of value based on amount*price, required fields for new transactions, and the optional use of tx_hash. No annotations are provided, so the description fully compensates.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is relatively long but well-structured with paragraphs separating normal trades, swaps, upsert behavior, and required fields. It is front-loaded with the main purpose. However, some content could be condensed, making it less concise than optimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (14 parameters, upsert behavior, swap handling) and the absence of an output schema, the description covers most behavioral aspects thoroughly. It mentions sibling tools for disambiguation. It does not explain the return value of the tool, which is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description explains the meanings of several key parameters (side, symbol, price, amount, fiat_value, fiat_currency, id, tx_hash, value). It does not explicitly cover all 14 parameters (e.g., notes, timestamp, exchange, fee_amount, fee_asset are mentioned as required but not detailed). The coverage is extensive enough to guide an agent, though not exhaustive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly defines the tool as recording a trade (BUY/SELL, including swaps) and differentiates it from the sibling log_transfer tool, specifying which tool to use for asset transfers without exchange. The verb 'Registra' and the resource 'trade' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when to use this tool vs the sibling log_transfer: 'Per spostare lo stesso asset tra due exchange/wallet, senza scambiarlo con un altro asset, usa invece il tool log_transfer.' Also explains how to handle crypto/crypto swaps, including the recommendation to provide fiat_value and fiat_currency for better P&L calculation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

log_transferA

Registra il movimento dello stesso asset tra due custodie (exchange o wallet), upsert per id. Non è un trade: non c'è side né un prezzo di scambio, quindi non usare questo tool per uno swap tra due asset diversi (per quello usa log_transaction).

    `exchange` è l'origine, `to_exchange` la destinazione. `symbol` è
    il solo asset spostato (es. "BTC"), non una coppia. `fee_amount`/
    `fee_asset` rappresentano la fee di rete del trasferimento, non una
    commissione di trading. `tx_hash` è fortemente consigliato quando
    disponibile (tipico per i prelievi/depositi on-chain). `fiat_value`/
    `fiat_currency` sono opzionali, per tracciare il controvalore fiat
    dell'importo spostato al momento del trasferimento.

    Se `id` è omesso viene generato automaticamente. Se `id`
    corrisponde a un transfer già salvato, solo i campi passati vengono
    aggiornati (merge parziale). Per un nuovo transfer sono richiesti
    exchange, to_exchange, symbol, timestamp, amount, fee_amount,
    fee_asset.
    
ParametersJSON Schema
NameRequiredDescriptionDefault
idNo
notesNo
amountNo
symbolNo
tx_hashNo
exchangeNo
fee_assetNo
timestampNo
fee_amountNo
fiat_valueNo
to_exchangeNo
fiat_currencyNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It explains upsert behavior (auto-generated ID, partial merge for existing records), required fields for new transfers, and the nature of fees (network fee, not trading commission). However, it does not explicitly address side effects like idempotency or potential data loss, slightly reducing completeness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and distinction, followed by parameter details and behavior. It is slightly verbose but every part adds value. No redundant sentences, but could be tightened slightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 12 parameters, upsert behavior, and no output schema, the description covers most essential aspects: both usage scenarios, parameter meanings, create vs. update behavior, and required fields. It doesn't describe the return value, but that's minor. Overall, it provides sufficient context for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. It explains key parameters: exchange (origin), to_exchange (destination), symbol (single asset), fee_amount/fee_asset (network fee), tx_hash (recommended), fiat_value/fiat_currency (optional). However, the 'notes' parameter is not mentioned, and 'amount' is implied but not explicitly defined, leaving a minor gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool logs asset movement between two custodians, uses 'upsert per id', and distinguishes it from a trade by noting no side or price. It also names the sibling tool log_transaction for swaps between different assets, making the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly says when to use (same-asset transfer between custodians) and when not to (different-asset swap, directing to log_transaction). It also advises using tx_hash for on-chain transfers, providing practical guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedget_transaction_history
    • First observedlog_transaction
    • First observedlog_transfer

TDQS

A4.1/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a distinct and clear purpose: one for querying history, one for logging trades/swaps, and one for logging asset transfers. There is no overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with lowercase and underscores: get_transaction_history, log_transaction, log_transfer. This is predictable and easy to understand.

Tool Count4/5

With only 3 tools, the set is minimal but covers the core actions of reading and writing transactions and transfers. It feels slightly thin but is still well-scoped for a focused server.

Completeness4/5

The server covers basic CRUD operations for transactions and transfers, including upsert and filtering. Missing a dedicated tool for single transaction retrieval or deletion, but the existing tools can accommodate those needs.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Agent-native, self-hosted MCP server for crypto trading and DeFi management. Enables agents to query balances, execute trades, and manage positions with a policy engine and secure key storage.
    7
    Apache 2.0
  • F
    license
    B
    quality
    D
    maintenance
    A powerful SQLite-backed expense tracking server built with the Model Context Protocol (MCP). This server allows AI agents (like Claude) to manage your personal finances by adding, deleting, and listing expenses directly from your chat interface.
    3
    -
  • A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for cryptocurrency trading across multiple exchanges (Bybit, Binance, KuCoin, etc.) with real-time price data, comparison, and natural language query support. Integrates with AI assistants via the Model Context Protocol.
    MIT
  • F
    license
    Not graded
    quality
    B
    maintenance
    A lightweight MCP server that lets LLM clients track, query, and summarize personal expenses using a local SQLite database.
    -