de en es it ja ko ru zh

crypto-transactions-mcp

Name: crypto-transactions-mcp
Author: bolesk

by bolesk

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

crypto-transactions-mcp

MCP server per tracciare transazioni e ordini eseguiti nel mercato crypto. Espone tool MCP che permettono a un agent LLM (Claude, agy, ecc.) di registrare trade, swap e trasferimenti con precisione Decimal esatta, e di interrogare lo storico — con persistenza intercambiabile su un file JSON locale o su un database Notion.

Quick Start

uv sync per installare le dipendenze.
Scegli un backend:
- JSON (default, zero config) — salta al punto 3.
- Notion — segui prima la sezione "Setup Notion da zero" qui sotto.
Aggiungi il server alla configurazione del tuo host MCP: vedi "Configurazione Claude Desktop" o "Configurazione agy".
Riavvia l'host e prova, ad esempio: "Ho comprato 0.1 BTC su Binance a 65000 USDT, fee 0.0001 BTC, registralo con log_transaction."

Architettura onion:

domain/ — entità CryptoTransaction (Pydantic v2, campi monetari in Decimal). side è BUY/SELL (trade, incluso uno swap crypto/crypto) oppure TRANSFER (spostamento dello stesso asset tra due custodie); i due casi hanno requisiti diversi validati nel modello stesso (BUY/SELL richiedono price/value, TRANSFER richiede to_exchange)
interfaces/ — port TransactionRepository e TransactionFilters
usecases/ — LogTransactionUseCase (trade, upsert con merge parziale), LogTransferUseCase (transfer, stessa semantica di upsert), GetTransactionHistoryUseCase
infrastructure/ — adapter concreti del port TransactionRepository:
- JsonTransactionRepository, file JSON locale, path fisso data/crypto_transactions.json
- NotionTransactionRepository, database Notion (vedi sotto)
delivery/ — server FastMCP, tool MCP (log_transaction, log_transfer, get_transaction_history), wiring delle dipendenze in factories.py

Related MCP server: Expense Tracker MCP Server

Tool MCP

log_transaction — trade BUY/SELL, incluso uno swap tra due crypto (es. ETH/BTC): stessa forma di un trade normale, non serve un tool a parte. Supporta fiat_value/fiat_currency opzionali per fissare il controvalore fiat al momento dello scambio — fortemente consigliato per gli swap crypto/crypto, dove il solo price (cambio relativo tra le due crypto) non permette di calcolare a posteriori il P&L realizzato né il cost-basis fiat del nuovo asset ricevuto.
log_transfer — spostamento dello stesso asset tra due custodie (exchange → to_exchange), non un trade: niente side/price, ma richiede to_exchange.
get_transaction_history — storico di entrambi, con filtri opzionali (symbol, exchange, side incluso "TRANSFER", date_from/date_to), ordinato per data decrescente (le più recenti prima) e paginato (limit default 50, offset); la risposta è {"transactions": [...], "has_more": bool}.
get_portfolio_summary — per ogni asset (escluso vs_currency stesso): quanto ne possiedi, quanto hai investito in totale e in media per unità (cost-basis), valore di mercato, plus/minusvalenza non realizzata. as_of_date opzionale per una situazione a una data passata (prezzo storico) invece che live — pensato per la rendicontazione fiscale. cost_basis_method (weighted_average o fifo) è una scelta esplicita, non automatica: possono dare plusvalenze diverse sullo stesso storico, verifica quale ti serve con un commercialista.
get_asset_price — quotazione di un singolo asset, corrente o storica a una data, senza calcolare tutto il portafoglio.

Setup

uv sync

Copia .env.example in .env e valorizzalo: viene caricato automaticamente all'avvio (main.py chiama load_dotenv()). Questo funziona anche quando il server è lanciato da un host esterno (Claude Desktop, agy, ...) con uv run --directory <path> main.py, perché --directory imposta la working directory del processo sulla root del progetto, dove load_dotenv() cerca .env di default — non serve duplicare i secret nel JSON di config dell'host, che spesso è meno protetto di un .env locale gitignored.

Backend di persistenza

Selezionabile con la variabile d'ambiente TRANSACTION_REPOSITORY_BACKEND:

json (default) — nessuna configurazione aggiuntiva richiesta.
notion — richiede NOTION_TOKEN (token dell'integration Notion) e NOTION_DATABASE_ID.

Setup Notion da zero

Se non hai già un'integration Notion collegata a questo progetto, segui questi passi in ordine (richiede un account Notion con permessi di creare integration nel workspace):

Crea l'integration — vai su notion.so/my-integrations → "+ New integration" → dai un nome (es. "Crypto Transactions MCP") → scegli il workspace → tipo "Internal".
Abilita le capabilities — nella pagina di configurazione dell'integration, sotto "Capabilities", abilita: Read content, Update content, Insert content.
Copia il token — tab "Secrets" → copia il valore di "Internal Integration Secret" (inizia con secret_ o ntn_). Questo è il tuo NOTION_TOKEN.
Crea il database — in Notion, crea un nuovo database (full-page o inline) e configuralo con esattamente le property elencate nella tabella sotto. La colonna "title" che Notion crea di default (di solito "Name") va rinominata in Transaction ID: ogni database Notion ne ha obbligatoriamente una, non è il nome del database ma la colonna che identifica ogni riga.
Condividi il database con l'integration — apri la pagina del database → menu "..." in alto a destra → "Connections" → cerca e collega l'integration creata al punto 1. Senza questo passaggio l'API risponde 404 anche con un token valido, perché i permessi Notion sono per-pagina, non workspace-wide.
Trova il database ID — è nell'URL della pagina del database: https://www.notion.so/<ID-senza-trattini>?v=.... Ad esempio, da https://www.notion.so/abcdef0123456789abcdef0123456789?v=... l'ID è abcdef0123456789abcdef0123456789. Questo è il tuo NOTION_DATABASE_ID.

Configura le variabili — nel tuo .env (vedi sopra), o nel blocco env dell'host MCP:

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

Il database Notion deve avere queste property (nome esatto e tipo):

Property	Tipo
`Transaction ID`	title
`Tx Hash`	rich_text
`Exchange`	select
`To Exchange`	select
`Symbol`	select
`Side`	select (`BUY`, `SELL`, `TRANSFER`)
`Timestamp`	date (con orario, 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 possono essere vuoti (non si applicano a un TRANSFER, o sono opzionali su un trade).

Nota: i campi numerici su Notion sono number nativi (float64), non Decimal esatti come nel backend JSON — sufficiente per gli importi reali di trading, ma soggetto ai limiti di precisione di un float a doppia precisione.

Test

uv run pytest

Esecuzione manuale

uv run main.py

Configurazione Claude Desktop

Aggiungi al file claude_desktop_config.json (su macOS: ~/Library/Application Support/Claude/claude_desktop_config.json). Con un .env già configurato alla root del progetto (vedi sopra) basta questo, nessun secret nel JSON:

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

In alternativa, se preferisci non usare un file .env, puoi passare le variabili direttamente nel blocco env (sovrascrivono quelle di .env se presenti entrambe):

{
  "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"
      }
    }
  }
}

Configurazione agy

Stesso schema mcpServers, ma nel file .agents/mcp_config.json alla root del progetto in cui usi agy (aggiungi la voce crypto-transactions accanto agli altri server già presenti, senza rimuoverli). Vale la stessa cosa: con .env configurato non serve il blocco env:

{
  "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

Name	Required	Description	Default
`side`	No
`symbol`	No
`date_to`	No
`exchange`	No
`date_from`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

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

Name	Required	Description	Default
`id`	No
`side`	No
`notes`	No
`price`	No
`value`	No
`amount`	No
`symbol`	No
`tx_hash`	No
`exchange`	No
`fee_asset`	No
`timestamp`	No
`fee_amount`	No
`fiat_value`	No
`fiat_currency`	No

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

Name	Required	Description	Default
`id`	No
`notes`	No
`amount`	No
`symbol`	No
`tx_hash`	No
`exchange`	No
`fee_asset`	No
`timestamp`	No
`fee_amount`	No
`fiat_value`	No
`to_exchange`	No
`fiat_currency`	No

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.

3 tool updatesv0.1.0Jul 14, 2026
- First observedget_transaction_history
- First observedlog_transaction
- First observedlog_transfer

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored 2026-07-14 10:50 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

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

gainium-mcpOAuth
io.gainium
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
Cryptocurrency Finance
22
agentic-commerce A
io.bosonprotocol
MCP server for Boson Protocol — on-chain agentic commerce for physical & digital goods.
Blockchain E-commerce & Retail Autonomous Agents
632
StateyOAuth
ai.statey
An agent-native database over MCP: shared, validated, structured records in every AI chat.
Databases Knowledge & Memory
2
Relm CRM A
com.relmcrm
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
CRM AI & Machine Learning
412

Related MCP Servers

seashailofficial
Blockchain Cryptocurrency Finance
seashail
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.
Updated 5 months ago (2026-04-29 05:55 UTC)
7
Apache 2.0
Expense Tracker MCP Server
Finance
Python-Blade
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.
Updated 8 months ago (2026-01-14 10:10 UTC)
3
-
bybit-trading
Cryptocurrency Finance Autonomous Agents
Vanszs
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.
Updated a year ago (2025-09-27 06:30 UTC)
MIT
ExpenseTracker MCP Server
Finance
axitmakwana45-cloud
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.
Updated 2 months ago (2026-07-17 06:50 UTC)
-

crypto-transactions-mcp

Quick Start

Tool MCP

Setup

Backend di persistenza

Setup Notion da zero

Test

Esecuzione manuale

Configurazione Claude Desktop

Configurazione agy

Available Tools

Output Schema

TDQS

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

seashailofficial

Expense Tracker MCP Server

bybit-trading

ExpenseTracker MCP Server