HEU Legal MCP Server

MCP server (Model Context Protocol) per integrare l'API HEU Legal con Claude (Claude Desktop, Claude Code, e altri client MCP). Gestisce documenti nativi HEU e PDF firmabili end-to-end via conversazione: creazione, condivisione per firma elettronica (valida in 180+ paesi), sollecito firmatari, download PDF.

Funzionalità

18 tool che coprono l'intera API HEU v1 più lettura contenuto e estrazione strutturata delle parti:

Documenti nativi HEU — list_heu_documents, get_heu_document, list_heu_document_placeholders, create_heu_document, prompt_heu_document_signature, extract_heu_document_parties, read_heu_document, download_heu_document_pdf

PDF caricati — list_pdf_documents, get_pdf_document, list_pdf_document_signers, list_pdf_document_signer_placeholders, list_pdf_document_placeholders, create_pdf_document, extract_pdf_document_parties, read_pdf_document, prompt_pdf_document_signature

Health — get_heu_health

Lettura del contenuto vs Download

Per ciascun tipo di documento esistono due modalità complementari:

I tool di lettura accettano un parametro opzionale pages per leggere solo un range (es. "1-3", "5", "1,3,5-7"). Senza pages leggono fino a un massimo di 100 pagine.

Requisiti

• Python ≥ 3.10
• Una API key HEU Legal (Profile → API Keys nella UI HEU; richiede subscription Enterprise)
• Almeno un template già creato sulla piattaforma HEU (documento nativo o PDF caricato)

Installazione

Da PyPI

pip install heu-mcp

Da sorgenti

git clone https://github.com/Lucav21/heu-mcp.git
cd heu-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Configurazione

Claude Desktop

Modifica ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "heu": {
      "command": "heu-mcp",
      "args": [],
      "env": {
        "HEU_API_KEY": "la_tua_api_key_qui"
      }
    }
  }
}

Se hai installato da sorgenti con venv:

{
  "mcpServers": {
    "heu": {
      "command": "/path/assoluto/heu-mcp/venv/bin/python",
      "args": ["/path/assoluto/heu-mcp/server.py"],
      "env": {
        "HEU_API_KEY": "la_tua_api_key_qui"
      }
    }
  }
}

Riavvia Claude Desktop dopo la modifica.

Claude Code (CLI)

claude mcp add heu heu-mcp -e HEU_API_KEY=la_tua_api_key_qui

Variabili d'ambiente

Esempi d'uso

Dopo aver configurato il MCP, chiedi a Claude:

• "Lista i miei template HEU"
• "Mostrami i firmatari del PDF con id 26"
• "Sollecita la firma del documento 15c587e0-1715-45c6-bf72-24bcb86c0f90"
• "Riassumi il contratto con id ... e dimmi qual è la durata" (usa read_heu_document)
• "Confronta i contratti X e Y, segnalami le differenze nelle clausole"
• *"Estrai i dati delle parti dal contratto

... View full README on GitHub