Dichiarino MCP

An MCP (Model Context Protocol) server that acts as an intelligent assistant for compiling the Italian Modello 730 Precompilato - the pre-filled annual income tax return.

What is Dichiarino?

Dichiarino is an MCP server that gives any compatible AI assistant (Claude Desktop, Cursor, etc.) deep knowledge of the Italian tax system and calculation tools for the 730 form. It embeds official fiscal rules, IRPEF rates, and deduction limits so the AI can guide you through your annual tax return.

Note: The Agenzia delle Entrate provides no public API for the 730 precompilato. Dichiarino works as a knowledge + calculation engine - it cannot submit your return for you. Always verify results with a qualified professional (CAF, commercialista, consulente del lavoro).

Features

Resources:

• dichiarino://aliquote/{anno} - IRPEF brackets and rates
• dichiarino://quadri/{nome} - Full instructions for each Quadro
• dichiarino://scadenze/{anno} - Key deadlines
• dichiarino://regioni - Regional surcharge table
• dichiarino://detrazioni - Full deduction limits table

Agent Skills

In addition to the MCP server, Dichiarino ships a set of portable Agent Skills in the skills/ folder - standalone instruction packages compatible with Claude, Cursor, and any agentskills.io-supported tool. They work without the MCP server but are enhanced when it is connected.

See skills/README.md for installation instructions.

Requirements

• Python 3.11+
• uv (recommended) or pip

Installation

# Clone the repo
git clone https://github.com/gsaccardi/dichiarino-mcp.git
cd dichiarino-mcp

# Install with uv
uv sync

Usage

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "dichiarino": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/dichiarino-mcp",
        "run",
        "dichiarino"
      ]
    }
  }
}

With Cursor or other MCP clients

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "dichiarino": {
      "command": "uv",
      "args": ["--directory", "/path/to/dichiarino-mcp", "run", "dichiarino"]
    }
  }
}

Run directly

uv run dichiarino
# or
uv run python -m dichiarino.main

Example Interactions

Once connected to Claude Desktop:

You: Quanto IRPEF devo pagare su un reddito di 35.000€?

Claude: [calls calcola_irpef + calcola_detrazione_lavoro]
        IRPEF lorda: 8.890€
        Detrazione lavoro: 1.565€ + bonus 65€
        IRPEF netta stimata: 7.260€

You: Ho speso 1.200€ dal medico quest'anno. Cosa posso detrarre?

Claude: [calls calcola_oneri]
        Spese sanitarie: 1.200€ - franchigia 129,11€ = 1.070,89€ x 19% = 203,47€
        Documenti necessari: fatture mediche, scontrini farmacia con CF

You: Quali quadri devo compilare? Ho lavoro dipendente, mutuo, e figli under 21.

Claude: [calls genera_checklist_730]
        Quadri: Frontespizio, C (lavoro), E (mutuo 19% su max 4.000€)
        ⚠️ I figli under 21 non generano detrazione - coperti dall'Assegno Unico Universale
        Documenti: CU datore, quietanza interessi banca, contratto mutuo

Development

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Lint
uv run ruff check src/ tests/

# Type check
uv run mypy src/

Project Structure

src/dichiarino/
├── main.py              # Entry point
├── server.py            # MCP server setup + registration
├── types.py             # Domain types
├── calculators/         # Pure calculation functions
│   ├── irpef.py
│   ├── detrazioni_lavoro.py
│   ├── detrazioni_familiari.py
│   ├── oneri.py
│   └── addizionali.py
├── validators/
│   └── codice_fiscale.py
├── data/                # Static fiscal data (2024)
│   ├── aliquote_irpef.py
│   ├── addizionali_regionali.py
│   ├── limiti_detrazioni.py
│   └── istruzioni_quadri.py
├── tools/               # MCP tool handlers
└── resources/           # MCP resource handlers

tests/
├── calculators/         # Unit tests for fiscal math
├── validators/          # Codice fiscale tests
└── integration/         # Full MCP server integration tests

Tax Year Coverage

Attribution

This project is licensed under the Apache License 2.0. If you redistribute this software or a Derivative Work, you must include the NOTICE file and retain the following attribution:

Powered by Dichiarino - https://github.com/gsaccardi/dichiarino-mcp

See LICENSE and NOTICE for full terms.

Disclaimer

The fiscal calculations provided are for informational purposes only and do not constitute professional tax or legal advice. Always verify your tax return with a qualified professional before submission. The authors accept no liability for errors or changes in fiscal legislation.