local-llm-mcp

Serveur MCP reliant Claude Code à LM Studio, pour déléguer à un modèle local les tâches coûteuses en tokens — sans sacrifier l'agentivité du modèle cloud.

Le principe

Le pilotage reste sur Claude ; seul le travail de volume part en local.

Le levier d'économie n'est pas « utiliser un modèle moins cher ». C'est empêcher le contenu brut d'entrer dans le contexte cloud : les outils lisent les fichiers eux-mêmes, côté serveur, et ne renvoient que le résultat du traitement.

Claude Code  ──(appel MCP : « résume src/**/*.cs »)──►  local-llm-mcp
                                                              │
                                                              ├─ lit les fichiers sur disque
                                                              ├─ découpe si > contexte local
                                                              └─ interroge LM Studio :1234
                                                                       │
Claude Code  ◄────────(≈700 tokens de synthèse)───────────────────────┘

Sans cet intermédiaire, lire une arborescence de sources consomme des dizaines de milliers de tokens de contexte. Avec, le coût se réduit à la taille de la réponse.

Related MCP server: Claude Sidekick

Mesures

Relevées sur un projet Godot/C# réel, avec qwen3-coder-30b :

Le rapport dépend entièrement de la tâche : une synthèse compresse beaucoup, une extraction exhaustive beaucoup moins.

Prérequis

• LM Studio avec son serveur local actif (port 1234 par défaut)

• Node.js 18 ou plus

• Claude Code

• Un modèle chargé — voir Choix du modèle ci-dessous

Testé sur Windows 11. server.js n'a pas de dépendance à Windows (le chemin de la CLI LM Studio est résolu selon la plateforme), mais seul le script d'appoint start-local.ps1 est spécifique à PowerShell.

Installation

git clone https://github.com/drangoht/local-llm-mcp.git
cd local-llm-mcp
npm ci

Puis enregistrer le serveur auprès de Claude Code, en donnant le chemin absolu vers server.js :

claude mcp add local-llm --scope user -- node /chemin/absolu/vers/local-llm-mcp/server.js

--scope user le rend disponible depuis tous vos projets. Utilisez --scope project pour le limiter au dépôt courant.

Vérification : claude mcp list doit afficher local-llm: ✔ Connected.

Outils exposés

Choix du modèle

Deux alias sont exposés :

Le défaut retenu est le plus gros modèle, ce qui mérite une explication car c'est contre-intuitif. Sur une même tâche courte, mesuré :

Le petit modèle est cinq fois plus rapide par token, mais en produit dix-huit fois plus pour un résultat équivalent. En sortie utile, le gros modèle gagne. Le paramètre enable_thinking: false n'a par ailleurs aucun effet sur ce modèle, et un max_tokens trop bas fait renvoyer un content vide — le serveur détecte ce cas et le signale explicitement au lieu de retourner une chaîne vide silencieuse.

À adapter à votre matériel via LOCAL_MODEL_CODE / LOCAL_MODEL_LIGHT.

Chargement automatique du modèle

Au démarrage, le serveur vérifie via lms ps --json que le modèle est chargé avec un contexte suffisant, et le recharge sinon.

Ce contrôle existe pour une raison précise : le réglage defaultContextLength de LM Studio vaut 4096 tokens. Son chargement à la demande (justInTimeModelLoading) ramène donc le modèle à 4096 dès que le TTL expire ou que l'application redémarre — et local_digest casse alors silencieusement : réponses tronquées, aucune erreur levée. C'est le mode de défaillance le plus pénible parce qu'il est invisible.

La vérification est non bloquante (le handshake MCP reste à ~0,4 s) et ne coûte rien quand la configuration est déjà correcte. La désactiver : LOCAL_AUTOLOAD=0.

start-local.ps1 (Windows) fait la même chose depuis un terminal, utile pour précharger le modèle avant d'ouvrir Claude Code et éviter l'attente au premier appel.

Configuration

Toutes les variables d'environnement sont optionnelles.

Restreindre les lectures

Par défaut le serveur peut lire n'importe quel fichier accessible à l'utilisateur. Pour le confiner à vos dossiers de code :

claude mcp add local-llm --scope user \
  --env LOCAL_ALLOWED_ROOTS="/chemin/vers/projets" \
  -- node /chemin/absolu/vers/local-llm-mcp/server.js

Timeouts côté Claude Code

Dans ~/.claude/settings.json :

"env": {
  "MCP_TIMEOUT": "60000",
  "MCP_TOOL_TIMEOUT": "900000"
}

MCP_TOOL_TIMEOUT généreux est nécessaire : un local_map sur plusieurs dizaines de fichiers prend plusieurs minutes.

Quand déléguer au local, quand rester en cloud

Règle courte : le local sert à réduire un volume, pas à trancher une question.

Limites

• Le modèle local se trompe. Il rate des cas limites et invente parfois des noms de méthodes. Sa sortie est un point de départ à vérifier, jamais une conclusion sur un point critique.

• Débit modeste sur un GPU qui ne loge pas le modèle entièrement en VRAM. Sur la configuration de référence (Radeon RX 9070, 16 Go), un modèle 30B en Q4 déborde d'environ 3,5 Go et tourne à ~13,5 tok/s. Un local_map sur 40 fichiers dure plusieurs minutes.

• Pas de streaming : les résultats arrivent d'un bloc.

• Un seul modèle résident si la VRAM est limitée ; alterner entre alias impose un rechargement (~16 s pour un modèle de 18 Go).

Dépannage

Licence

MIT — voir LICENSE.