MCP Buste Paga

MCP Buste Paga

An MCP (Model Context Protocol) server that parses Italian INAZ payslip PDFs and stores them in a local SQLite database. Connect it to any MCP-compatible AI client to analyze your salary history, search payslip items, and get detailed breakdowns — all with your data staying on your machine.

Installation

Requirements: Python 3.10+, uv

Clone the repository and install dependencies:

git clone https://github.com/morettimarco/MCP-Buste-Paga.git
cd MCP-Buste-Paga
uv sync

Verify it runs:

uv run mcp-buste-paga

Ingesting payslips

Once the server is connected to an AI client (see below), ask the assistant to ingest your payslip PDFs:

"Ingest my payslips from ~/Documents/Buste"

The ingest_payslips tool will recursively scan the directory for .pdf files, parse each one, and store the data. Duplicates are automatically skipped via SHA-256 hashing.

Database location

All data is stored in a local SQLite database at:

~/.mcp-buste-paga/buste_paga.db

The directory is created automatically on first run. The database contains four tables:

| Table | Description | |---|---| | aziende | Company information (name, fiscal code, INPS/INAIL codes) | | dipendenti | Employee profile (name, fiscal code, hire date, role, contract) | | buste_paga | Monthly payslip summaries (gross, net, taxes, TFR, etc.) | | voci_corpo_busta | Individual payslip line items (base pay, overtime, deductions, etc.) |

Available tools

| Tool | Description | |---|---| | ingest_payslips | Scan a directory for PDF payslips, parse and store them. Returns a summary of ingested/skipped/failed files. | | get_employee_summary | Get employee profile and company details, plus the number of payslips stored. | | get_salary_history_tool | Get salary history (net pay, gross, deductions) ordered by most recent month. Optionally filter by year. | | get_payslip_details_tool | Get the full breakdown of a specific payslip by month and year, including all line items. | | search_payslip_items | Search payslip line items by keyword (e.g. "Straordinario", "Ferie", "Ticket") with per-month and grand totals. |

Connecting to AI clients

Claude Desktop

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

{
  "mcpServers": {
    "buste-paga": {
      "command": "/full/path/to/uv",
      "args": [
        "--directory",
        "/full/path/to/MCP-Buste-Paga",
        "run",
        "mcp-buste-paga"
      ]
    }
  }
}

Note: Use absolute paths. Find your uv path with which uv.

Restart Claude Desktop. A hammer icon in the chat input confirms the server is connected.

Claude Code (CLI)

Add to your project's .mcp.json or run:

claude mcp add buste-paga -- uv --directory /full/path/to/MCP-Buste-Paga run mcp-buste-paga

ChatGPT Desktop

ChatGPT Desktop supports MCP servers via its settings. Go to Settings > Beta features > MCP Servers, click Add, and configure:

• Name: buste-paga
• Command: /full/path/to/uv
• Arguments: --directory /full/path/to/MCP-Buste-Paga run mcp-buste-paga

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "buste-paga": {
      "command": "/full/path/to/uv",
      "args": [
        "--directory",
        "/full/path/to/MCP-Buste-Paga",
        "run",
        "mcp-buste-paga"
      ]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "buste-paga": {
      "command": "/full/path/to/uv",
      "args": [
        "--directory",
        "/full/path/to/MCP-Buste-Paga",
        "run",
        "mcp-buste-paga"
      ]
    }
  }
}

Privacy

All payslip data is parsed and stored locally on your machine. No data is sent to external services. The AI client only accesses the data through the MCP tools above.

License

MIT