HEU Legal MCP Server

MCP server (Model Context Protocol) che collega l'API HEU Legal a Claude e a qualsiasi client MCP. Gestisce l'intero ciclo di vita dei documenti con firma elettronica (valida in 180+ paesi) direttamente in conversazione: dalla creazione all'invio in firma, dal sollecito al download del fascicolo legale completo.

Cosa puoi fare

Due famiglie di oggetti:

• Documenti nativi HEU — creati con l'editor in-app della piattaforma (ID a forma di UUID, es. 5135e7b2-196b-...).
• PDF caricati — file PDF con firmatari e campi firma posizionati sopra (ID numerici, es. 68).

Requisiti

• Python ≥ 3.10
• API key HEU Legal — nella UI: Profile → API Keys → Generate API Key (richiede subscription Enterprise; massimo 2 chiavi attive)
• Per i flussi da template: almeno un template creato sulla piattaforma (oppure crealo via API con create_pdf_template)

Installazione

Da PyPI:

pip install heu-mcp

Da sorgenti:

git clone https://github.com/heulegal/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 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

Server remoto (multi-utente)

Oltre alla modalità locale (stdio) descritta sopra, il progetto include un server remoto che espone gli stessi 28 tool via HTTPS, così gli utenti si collegano senza installare nulla: inseriscono la propria API key HEU una volta, in un flusso OAuth.

Caratteristiche:

• Transport Streamable HTTP, autenticazione OAuth 2.1 con PKCE S256, Dynamic Client Registration e Client ID Metadata Document
• Multi-utente: ogni connessione usa la API key del proprio utente, conservata cifrata (Fernet) e mai in chiaro nel database
• Refresh token con rotazione e revoca automatica della sessione in caso di riuso sospetto
• I/O di rete asincrono e parsing PDF su threadpool: una richiesta lenta non blocca gli altri utenti

Avvio locale

pip install -e ".[remote]"
export HEU_MCP_SECRET_KEY="$(python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')"
export PUBLIC_URL="http://localhost:8080"
export HEU_MCP_DB="./heu-mcp.db"
heu-mcp-remote

Deploy su Fly.io

fly launch --no-deploy
fly volumes create heu_data --size 1
fly secrets set HEU_MCP_SECRET_KEY="$(python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')"
fly secrets set PUBLIC_URL="https://<nome-app>.fly.dev"
fly deploy

Variabili d'ambiente del server remoto

Endpoint esposti

Variabili d'ambiente

Riferimento completo dei tool (28)

🩺 Health

📄 Documenti nativi HEU

📎 PDF caricati

Read the full README on GitHub →