Connexion des clients IA

Ce guide explique comment connecter les principaux clients IA au serveur mcp_jeedom installé sur votre serveur Jeedom (Debian/Linux).

ℹ️ Prérequis — Le daemon mcp_jeedom doit être démarré et son statut doit afficher ✓ Actif dans la page de configuration du plugin.

Architecture de connexion

Deux modes de connexion sont disponibles selon la situation réseau du client IA.

Accès local (réseau LAN)

Connexion directe sans authentification. Le client IA contacte le daemon sur son port (défaut : 8765).

Client IA (poste local)  →  http://IP_JEEDOM:8765/mcp  →  Daemon mcp_jeedom  →  API Jeedom

Accès externe (Internet)

Connexion via le proxy PHP intégré avec authentification Bearer. Nécessite un token généré dans la page de configuration.

Client IA (n'importe où)  →  HTTPS  →  jeemcp_proxy.php  →  Daemon mcp_jeedom  →  API Jeedom

Prérequis communs

Installer `uv` / `uvx`

La plupart des clients IA utilisent uvx (fourni par uv) pour lancer mcp-remote à la demande.

macOS

brew install uv
# ou sans Homebrew :
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell)

winget install astral-sh.uv -e

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc   # ou source ~/.zshrc

ℹ️ Après installation, redémarrez votre terminal (ou le client IA) pour que uvx soit disponible dans le PATH.

Valeurs à remplacer

Dans tous les exemples ci-dessous :

Placeholder	Valeur réelle
`IP_JEEDOM`	IP locale de votre serveur Jeedom (ex : `192.168.1.79`)
`PORT`	Port du daemon (défaut : `8765`)
`VOTRE_TOKEN`	Token généré dans Plugins → mcp_jeedom → Token d’accès externe
`VOTRE_URL_EXTERNE`	URL publique de votre Jeedom (ex : `https://jeedom.exemple.fr`)

Claude Desktop

Transport recommandé : Streamable HTTP via mcp-remote

Éditez le fichier de configuration Claude Desktop :

OS	Chemin
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Accès local LAN

{
  "mcpServers": {
    "jeedom_mcp": {
      "command": "uvx",
      "args": [
        "mcp-remote@latest",
        "http://IP_JEEDOM:PORT/mcp"
      ]
    }
  }
}

Accès externe (Internet)

{
  "mcpServers": {
    "jeedom_mcp": {
      "command": "uvx",
      "args": [
        "mcp-remote@latest",
        "https://VOTRE_URL_EXTERNE/plugins/mcp_jeedom/core/php/jeemcp_proxy.php",
        "--header", "Authorization: Bearer VOTRE_TOKEN"
      ]
    }
  }
}

Après modification, quitter et relancer complètement Claude Desktop.

Vérification : Icône 🔧 en bas à gauche → jeedom_mcp doit apparaître dans la liste.

Claude Code

Accès local

claude mcp add jeedom_mcp \
  --transport http \
  "http://IP_JEEDOM:PORT/mcp"

Accès externe

claude mcp add jeedom_mcp \
  --transport http \
  --header "Authorization: Bearer VOTRE_TOKEN" \
  "https://VOTRE_URL_EXTERNE/plugins/mcp_jeedom/core/php/jeemcp_proxy.php"

Vérification :

claude mcp list

Claude.ai (web)

Transport : HTTP uniquement — nécessite une URL accessible depuis Internet.

Aller dans claude.ai → Paramètres → Intégrations
Cliquer Ajouter un serveur MCP
Renseigner :
- URL : https://VOTRE_URL_EXTERNE/plugins/mcp_jeedom/core/php/jeemcp_proxy.php
- En-tête : Authorization: Bearer VOTRE_TOKEN

⚠️ claude.ai ne peut pas atteindre un serveur sur votre réseau local. Utilisez Cloudflare Tunnel ou un reverse proxy si vous n’avez pas d’URL publique.

Cursor

Via l’interface

Cursor → Settings → Cursor Settings → MCP
Cliquer + Add new MCP server

Via .cursor/mcp.json (à la racine du projet)

{
  "mcpServers": {
    "jeedom_mcp": {
      "command": "uvx",
      "args": [
        "mcp-remote@latest",
        "http://IP_JEEDOM:PORT/mcp"
      ]
    }
  }
}

Accès externe

{
  "mcpServers": {
    "jeedom_mcp": {
      "command": "uvx",
      "args": [
        "mcp-remote@latest",
        "https://VOTRE_URL_EXTERNE/plugins/mcp_jeedom/core/php/jeemcp_proxy.php",
        "--header", "Authorization: Bearer VOTRE_TOKEN"
      ]
    }
  }
}

VS Code / GitHub Copilot

Via .vscode/mcp.json (workspace)

{
  "servers": {
    "jeedom_mcp": {
      "type": "http",
      "url": "http://IP_JEEDOM:PORT/mcp"
    }
  }
}

Accès externe avec token

{
  "servers": {
    "jeedom_mcp": {
      "type": "http",
      "url": "https://VOTRE_URL_EXTERNE/plugins/mcp_jeedom/core/php/jeemcp_proxy.php",
      "headers": {
        "Authorization": "Bearer VOTRE_TOKEN"
      }
    }
  }
}

Windsurf

Fichier : ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "jeedom_mcp": {
      "command": "uvx",
      "args": [
        "mcp-remote@latest",
        "http://IP_JEEDOM:PORT/mcp"
      ]
    }
  }
}

Cline

Ouvrir la vue Cline dans VS Code
MCP Servers → Configure MCP Servers
Ajouter dans cline_mcp_settings.json :

{
  "mcpServers": {
    "jeedom_mcp": {
      "command": "uvx",
      "args": [
        "mcp-remote@latest",
        "http://IP_JEEDOM:PORT/mcp"
      ],
      "disabled": false
    }
  }
}

Continue

Fichier : ~/.continue/config.yaml

Accès local

mcpServers:
  - name: jeedom_mcp
    transport:
      type: http
      url: http://IP_JEEDOM:PORT/mcp

Accès externe

mcpServers:
  - name: jeedom_mcp
    transport:
      type: http
      url: https://VOTRE_URL_EXTERNE/plugins/mcp_jeedom/core/php/jeemcp_proxy.php
      headers:
        Authorization: "Bearer VOTRE_TOKEN"

ChatGPT

Transport : HTTP uniquement — nécessite une URL accessible depuis Internet (même contrainte que Claude.ai).

ChatGPT → Paramètres → Connecteurs
Ajouter un connecteur MCP :
- URL : https://VOTRE_URL_EXTERNE/plugins/mcp_jeedom/core/php/jeemcp_proxy.php
- En-tête : Authorization: Bearer VOTRE_TOKEN

Gemini CLI

Accès local

gemini mcp add --name jeedom_mcp \
  --type http \
  --url "http://IP_JEEDOM:PORT/mcp"

Accès externe

gemini mcp add --name jeedom_mcp \
  --type http \
  --url "https://VOTRE_URL_EXTERNE/plugins/mcp_jeedom/core/php/jeemcp_proxy.php" \
  --header "Authorization: Bearer VOTRE_TOKEN"

Open WebUI

Transport : HTTP uniquement.

Open WebUI → Paramètres → Connexions
Ajouter un serveur MCP :
- URL : http://IP_JEEDOM:PORT/mcp
- Type : Streamable HTTP

ℹ️ Si Open WebUI tourne sur un hôte différent de Jeedom, utiliser l’IP réseau de Jeedom. Sur le même hôte : http://localhost:PORT/mcp.

JetBrains IDEs

Via le plugin AI Assistant :

Settings → Tools → AI Assistant → Model Context Protocol (MCP)
Cliquer + → As stdio process
Configurer :
- Command : uvx
- Arguments : mcp-remote@latest http://IP_JEEDOM:PORT/mcp

Zed

Fichier : ~/.config/zed/settings.json

{
  "context_servers": {
    "jeedom_mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-remote@latest",
          "http://IP_JEEDOM:PORT/mcp"
        ]
      }
    }
  }
}

Raycast

Nécessite : Raycast Pro.

Raycast → Settings → Extensions → MCP Servers
Cliquer + → HTTP Server
Renseigner :
- Name : jeedom_mcp
- URL : http://IP_JEEDOM:PORT/mcp

Codex (OpenAI CLI)

Fichier : ~/.codex/config.toml

ℹ️ Codex utilise le format TOML (et non YAML). La syntaxe native avec url est la seule méthode fiable, en particulier sous Windows où le PATH peut ne pas être disponible dans le contexte sandboxé de Codex.

Accès local LAN

[mcp_servers.jeedom_mcp]
url = "http://IP_JEEDOM:PORT/mcp"

Accès externe (Internet)

[mcp_servers.jeedom_mcp]
url = "https://VOTRE_URL_EXTERNE/plugins/mcp_jeedom/core/php/jeemcp_proxy.php"
headers = { Authorization = "Bearer VOTRE_TOKEN" }

⚠️ Ne pas utiliser command + args avec uvx mcp-proxy sous Windows : le sandbox élévé de Codex ne résout pas le PATH utilisateur, ce qui provoque une erreur silencieuse. La clé url contourne ce problème en se connectant directement au daemon via HTTP.

Tableau récapitulatif

Client	LAN	Externe	Config
Claude Desktop	✅	✅	`claude_desktop_config.json`
Claude Code	✅	✅	`claude mcp add`
Claude.ai (web)	❌	✅	Interface web
Cursor	✅	✅	`.cursor/mcp.json`
VS Code / Copilot	✅	✅	`.vscode/mcp.json`
Windsurf	✅	✅	`mcp_config.json`
Cline	✅	✅	`cline_mcp_settings.json`
Continue	✅	✅	`~/.continue/config.yaml`
ChatGPT	❌	✅	Interface web
Gemini CLI	✅	✅	`gemini mcp add`
Open WebUI	✅	✅	Interface web
JetBrains IDEs	✅	✅	Settings AI Assistant
Zed	✅	✅	`~/.config/zed/settings.json`
Raycast	✅	✅	Interface Raycast
Codex	✅	✅	`~/.codex/config.toml`

ℹ️ LAN ❌ signifie que le client tourne sur les serveurs du fournisseur et ne peut pas atteindre votre réseau local. Une URL publique est obligatoire.

Dépannage

`uvx` introuvable après installation

source ~/.bashrc      # bash
source ~/.zshrc       # zsh
~/.local/bin/uvx --version   # vérifier le chemin complet

Tester le serveur directement

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  http://IP_JEEDOM:PORT/mcp

Une réponse JSON contenant "protocolVersion" confirme que le serveur répond correctement.

Le serveur n’apparaît pas dans le client

Vérifier que le daemon est Actif dans la page de configuration Jeedom
Vérifier que le port n’est pas bloqué par un firewall côté Jeedom
Vérifier la syntaxe JSON du fichier de configuration (pas de virgule finale, guillemets corrects)
Redémarrer complètement le client IA (ne pas juste fermer la fenêtre)

Erreur SSL (certificat auto-signé)

Ajouter --allow-insecure à mcp-remote, ou utiliser Cloudflare Tunnel qui gère automatiquement le TLS.

Token refusé (401 / 403)

Vérifier que le token est copié sans espace ni retour à la ligne
Ne pas encadrer le token de guillemets dans les variables d’environnement
Régénérer le token depuis Plugins → mcp_jeedom → Token d’accès externe si nécessaire

Claude ne voit pas les outils

Demander à Claude : « Liste tes outils disponibles » — si jeedom_mcp est connecté, Claude listera get_full_state, find_command, etc.

Dans Claude Desktop : Paramètres → Développeur → Serveurs MCP locaux pour voir les erreurs éventuelles.

*mcp_jeedom — Documentation

Plugin open-source pour Jeedom*

Connexion des clients IA

Architecture de connexion

Accès local (réseau LAN)

Accès externe (Internet)

Prérequis communs

Installer uv / uvx

Valeurs à remplacer

Claude Desktop

Claude Code

Claude.ai (web)

Cursor

VS Code / GitHub Copilot

Windsurf

Cline

Continue

ChatGPT

Gemini CLI

Open WebUI

JetBrains IDEs

Zed

Raycast

Codex (OpenAI CLI)

Tableau récapitulatif

Dépannage

uvx introuvable après installation

Tester le serveur directement

Le serveur n’apparaît pas dans le client

Erreur SSL (certificat auto-signé)

Token refusé (401 / 403)

Claude ne voit pas les outils

Installer `uv` / `uvx`

`uvx` introuvable après installation