Freshsales su MCP: contatti, account, trattative, attività e attività commerciali in qualsiasi agente AI

💡 Niente installazione? Vai direttamente su cloud.anythingmcp.com. Accedi, clicca Connectors → Freshsales, inserisci le credenziali, genera una MCP API key e hai finito. Niente Docker, niente git clone, niente server locale.

Freshsales

Freshsales (Freshworks CRM) da qualsiasi agente AI: cerca e filtra contatti, account e trattative, sposta le trattative tra le fasi della pipeline, aggiungi note, pianifica attività e appuntamenti, registra attività commerciali e gestisci le liste marketing. Funziona con la chiave API personale di un utente e l'URL bundle del tuo account.

Setup

La configurazione richiede circa 2 minuti. Ti serve un account Freshsales (Freshworks CRM).

1. In Freshsales fai clic sulla tua immagine del profilo, poi su Profile Settings, e apri la scheda API Settings.
2. Copia Your API key in FRESHSALES_API_KEY. Il connettore la invia come Authorization: Token token=<key>, quindi incolla solo la chiave.
3. Nella stessa scheda copia il bundle alias (l'indirizzo del tuo account) in FRESHSALES_BUNDLE_URL, per esempio https://acme.myfreshworks.com/crm/sales. Gli account creati prima della suite Freshworks usano https://acme.freshsales.io. Ometti /api e la barra finale.
4. Installa il connettore ed esegui freshsales_list_owners: elenca gli utenti del portale e conferma chiave e indirizzo.

Ogni chiamata agisce con i permessi dell'utente di cui hai inserito la chiave: i record fuori dal suo ambito restano invisibili. Usa la chiave di un utente che vede i dati di cui il team ha bisogno.

Da dove partire: freshsales_list_owners restituisce gli id utente da usare come owner_id. freshsales_list_selector legge una picklist (territori, pipeline e fasi, valute, tipi e motivi delle trattative, fonti dei lead, settori e tipi di azienda, campagne, stati dei contatti, fasi del ciclo di vita, tipi ed esiti delle attività commerciali) e restituisce gli id da usare in scrittura. freshsales_list_pipeline_stages dà le fasi di una pipeline. freshsales_list_fields elenca i campi di contatti, account, trattative o attività commerciali, compresi quelli personalizzati: i loro nomi interni iniziano con cf_ e vanno in custom_field.

Trovare i record:

• freshsales_search: ricerca testuale per nome o email su contatti, account, trattative e utenti. include accetta i nomi al singolare contact, sales_account, deal e user; al plurale non restituisce nulla.
• freshsales_lookup: corrispondenza esatta su un campo, per esempio contatti per email, o contatti, account e trattative per nome o per il valore di un campo personalizzato.
• freshsales_filtered_search: regole sui campi (valori esatti, intervalli, liste), restituisce i record completi.
• Gli elenchi passano sempre da una vista salvata: freshsales_list_views dà gli id delle viste (per esempio "All Contacts" o "My Deals"), poi freshsales_list_contacts, freshsales_list_accounts o freshsales_list_deals leggono la vista con l'ordinamento.

Contatti, account e trattative: freshsales_get_contact, freshsales_get_account e freshsales_get_deal leggono un record e incorporano i record collegati con include (per esempio sales_accounts,deals,notes). freshsales_list_contact_activities mostra la cronologia di un contatto (email, chiamate, note, modifiche ai campi, visite web). Per scrivere l'AI usa freshsales_create_contact (almeno email o cognome), freshsales_update_contact, freshsales_upsert_contact (crea o aggiorna per email o per un altro campo univoco), freshsales_create_account (name univoco), freshsales_update_account, freshsales_create_deal (name e amount obbligatori) e freshsales_update_deal. Una trattativa avanza quando deal_stage_id viene impostato su una fase della sua pipeline; anche vinta e persa sono fasi, e una trattativa persa può avere un deal_reason_id. Gli aggiornamenti cambiano solo i campi passati.

Note, attività, appuntamenti e attività commerciali si collegano a un record con targetable_type (Contact, SalesAccount o Deal) e targetable_id:

• Note: freshsales_create_note, freshsales_update_note.
• Attività: freshsales_list_tasks (un filtro per chiamata: open, due_today, due_tomorrow, overdue o completed), freshsales_get_task, freshsales_create_task, freshsales_update_task, freshsales_complete_task.
• Appuntamenti: freshsales_list_appointments (open per i prossimi, past per quelli passati; i portali più vecchi usano upcoming), freshsales_get_appointment, freshsales_create_appointment, freshsales_update_appointment. I partecipanti sono utenti (FdMultitenant::User) o contatti (Contact).
• Attività commerciali come chiamate e visite registrate: freshsales_list_sales_activities, freshsales_get_sales_activity, freshsales_create_sales_activity.

Liste marketing: freshsales_list_marketing_lists, freshsales_list_marketing_list_contacts, freshsales_add_contacts_to_list e freshsales_remove_contacts_from_list (i contatti restano nel CRM).

Lead: gli account Freshsales attuali tengono i potenziali clienti come contatti con una fase del ciclo di vita; non esiste un modulo lead separato. L'AI filtra i contatti per fase del ciclo di vita tramite una vista o freshsales_filtered_search.

Disattivati all'installazione: nessuno. Il connettore non ha strumenti di cancellazione, quindi non può eliminare contatti, account, trattative, note, attività o appuntamenti. Creare e modificare record cambia il tuo CRM reale, quindi chiedi all'AI di mostrarti i campi prima di salvare.

Formati dei dati: i timestamp tornano in UTC o con offset (2026-02-13T23:27:49Z). Le date in ingresso accettano YYYY-MM-DD o ISO 8601; senza fuso si assume UTC. Gli importi sono nella valuta della trattativa; base_currency_amount è convertito nella valuta del portale. I campi vuoti sono null. I record incorporati con include arrivano in array separati di primo livello (users, sales_accounts, deals) accanto al record, collegati per id.

Paginazione: gli elenchi accettano page (da 1) e per_page (predefinito 25, massimo 100) e restituiscono meta.total_pages e meta.total. freshsales_search restituisce 10 risultati di default, al massimo 100.

Limiti ed errori comuni: 1000 richieste all'ora per account; oltre, Freshsales risponde 429. 401 indica una chiave errata o mancante, 403 che l'utente non ha il permesso o la funzione non è nel piano, 404 un id errato o un URL bundle sbagliato. Gli errori di validazione tornano come 400 con errors.message.

Il connettore non elimina record, non invia email e non modifica impostazioni del portale, campi o pipeline.

Prerequisiti: FRESHSALES_BUNDLE_URL, FRESHSALES_API_KEY

Installazione locale del connettore

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Apri http://localhost:3000/connectors/store, scegli Freshsales e inserisci le variabili elencate nei Prerequisiti.

Tool disponibili

Esempi di prompt

• "Trova il contatto [email protected] e mostrami le sue trattative aperte e le ultime note sul suo record."
• "Elenca le mie trattative aperte con chiusura prevista questo mese, con importo e fase."
• "Sposta la trattativa Rinnovo Acme nella fase Negoziazione e aggiungi una nota che il preventivo è stato inviato."
• "Quali delle mie attività sono scadute? Raggruppale per account collegato."
• "Registra una chiamata di 30 minuti con Tom Becker per oggi e crea un'attività di follow-up per martedì prossimo alle 10:00."

Prossimi passi

• Collegare a Claude
• Collegare a ChatGPT