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

1. uv sync per installare le dipendenze.
2. Scegli un backend:
   • JSON (default, zero config) — salta al punto 3.
   • Notion — segui prima la sezione "Setup Notion da zero" qui sotto.
3. Aggiungi il server alla configurazione del tuo host MCP: vedi "Configurazione Claude Desktop" o "Configurazione agy".
4. 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

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

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

1. Crea l'integration — vai su notion.so/my-integrations → "+ New integration" → dai un nome (es. "Crypto Transactions MCP") → scegli il workspace → tipo "Internal".
2. Abilita le capabilities — nella pagina di configurazione dell'integration, sotto "Capabilities", abilita: Read content, Update content, Insert content.
3. Copia il token — tab "Secrets" → copia il valore di "Internal Integration Secret" (inizia con secret_ o ntn_). Questo è il tuo NOTION_TOKEN.
4. 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.
5. 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.
6. 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.
7. 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"
      ]
    }
  }
}