Prerequisiti

• Python 3.11+ disponibile sul PATH (i tre server sono Python).
• I tre pacchetti installati editabili o da PyPI (quando rilasciati):ckan-mcp-server, istat-mcp-server, osm-mcp.
• Per installare in locale:

  git clone https://github.com/agent-engineering-studio/opendata-ai.git
  cd opendata-ai
  pip install -e ./ckan-mcp-server -e ./istat-mcp-server -e ./osm-mcp

Claude Desktop

Modifica claude_desktop_config.json (su macOS: ~/Library/Application Support/Claude/claude_desktop_config.json).

{
  "mcpServers": {
    "opendata-ckan": {
      "command": "ckan-mcp",
      "env": { "TRANSPORT": "stdio" }
    },
    "opendata-istat": {
      "command": "istat-mcp",
      "env": { "TRANSPORT": "stdio" }
    },
    "opendata-osm": {
      "command": "osm-mcp",
      "env": { "TRANSPORT": "stdio" }
    }
  }
}

Riavvia Claude Desktop. Nel selettore MCP vedrai i tre server con i loro tool (es. opendata-ckan/package_search). Per chiamarli basta fare la domanda in chat: Claude sceglie il tool.

Cursor

Cursor legge la stessa convenzione MCP. Modifica ~/.cursor/mcp.json (o il file Project settings):

{
  "mcpServers": {
    "opendata-ckan": {
      "command": "ckan-mcp",
      "env": { "TRANSPORT": "stdio" }
    },
    "opendata-istat": {
      "command": "istat-mcp",
      "env": { "TRANSPORT": "stdio" }
    },
    "opendata-osm": {
      "command": "osm-mcp",
      "env": { "TRANSPORT": "stdio" }
    }
  }
}

Riapri Cursor: i tool MCP appaiono nel pannello laterale come chiamate disponibili all'agent.

Esempio di sessione (Claude Desktop)

Una volta caricati i server, queste sono domande tipiche che Claude smista da solo ai tool MCP:

• “Cerca su dati.gov.it dataset sulla qualità dell'aria negli ultimi 12 mesi” → package_search
• “Quali sono i dataflow ISTAT sul lavoro?” → search_dataflows
• “Trasforma queste coordinate in un indirizzo” → reverse_geocode
• “Disegna su mappa i confini comunali di questo GeoJSON” → render_map_html

Troubleshooting

• Server non parte → controlla che which ckan-mcp restituisca il path giusto e che la venv contenente il pacchetto sia attiva nello stesso shell che avvia il client.
• Tool list vuota → il client deve usare il protocollo MCP recente (≥ 2025-03). Aggiorna Claude Desktop / Cursor all'ultima versione.
• Errori di rete dal tool → i tool fanno fetch verso il portale CKAN o l'endpoint SDMX. Verifica che la macchina abbia accesso a Internet senza proxy bloccante.