fattureincloud

This MCP server provides a set of tools to manage Italian electronic invoices through natural language, integrated with Claude AI and other MCP clients. It exposes 20 tools such as list_invoices, get_invoice, get_pdf_url, list_clients, create_invoice, send_to_sdi, and more, enabling you to browse, create, update, and send invoices, credits, and proformas, as well as manage clients and view financial dashboards. Use the tools in conversational prompts to perform common tasks like listing invoices by year/month, converting proformas to invoices, duplicating invoices with updated SDI codes, or sending documents to the SDI. The server returns structured data and direct links (PDFs, web views) for documents when available, making it easy to present results in your assistant workflows.

Prerequisites:

• Python 3.10+
• An account with Fatture in Cloud and API access enabled
• Claude Desktop or another MCP client

1. Clone the repository

git clone https://github.com/aringad/fattureincloud-mcp.git
cd fattureincloud-mcp

2. Create a virtual environment and install dependencies

python -m venv venv
source venv/bin/activate  # Linux/Mac
# Windows: venv\Scripts\activate

pip install -r requirements.txt

3. Configure credentials

cp .env.example .env

Edit the .env file to include your API token, company ID, and sender email:

FIC_ACCESS_TOKEN=your_api_token
FIC_COMPANY_ID=your_company_id
FIC_SENDER_EMAIL=your_email@example.com

4. Configure Claude Desktop (path examples shown for macOS; adapt to Windows/Linux as needed)

{
  "mcpServers": {
    "fattureincloud": {
      "command": "/full/path/to/fattureincloud-mcp/venv/bin/python",
      "args": ["/full/path/to/fattureincloud-mcp/server.py"],
      "env": {
        "FIC_ACCESS_TOKEN": "your_api_token",
        "FIC_COMPANY_ID": "your_company_id",
        "FIC_SENDER_EMAIL": "billing@yourcompany.com"
      }
    }
  }
}

5. Restart Claude Desktop to apply changes.

Note: Ensure the paths in the configuration match your environment and that the Python virtual environment is active when running the server.

Tips and notes:

• All write operations (create, send_to_sdi) require explicit confirmation in workflows.
• Invoices are created as drafts until you explicitly send them to the SDI.
• The SDI code is generated automatically from the client data.
• If you encounter authentication issues, double-check that FIC_ACCESS_TOKEN and COMPANY_ID are correct and that the token has sufficient permissions.
• Keep your dependencies up to date by periodically pulling changes from the repository and re-installing requirements.
• For security, limit exposure of API tokens and avoid embedding them in prompts or logs.