Skillget

llm-council-mcp-server

mcp
Security Audit
Warn
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Pass
  • Code scan — Scanned 10 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Local MCP server running Andrej Karpathy's 3-stage LLM Council via OpenRouter — a multi-model "second opinion" for Claude Code, Codex CLI & Antigravity. By Alexander Deja · anderzlabs.de

README.md

LLM Council MCP

English Version | Deutsche Version

English Version

Table of Contents

A lightweight, local MCP server for your Mac based on the original idea by Andrej Karpathy (karpathy/llm-council) with prompt/workflow templates ported from DmitryBMsk/llm-council-plus. It replicates the 3-stage workflow using the exact original prompts directly against OpenRouter, without any Docker or NAS dependencies. Works with Claude Code, Codex CLI, and Antigravity via MCP.

What it is (and how it works)

This tool replicates the AI deliberation process of the original project in three simple steps:

  1. Stage 1 (Answering): Several AI models answer your question independently and at the same time.
  2. Stage 2 (Reviewing): The models read all the answers without knowing who wrote which answer (blind review). Each model ranks the answers from best to worst to prevent self-bias.
  3. Stage 3 (Synthesis): A final "Chairman" model reads all answers and reviews, and writes a single, balanced response for you. If the Chairman fails, another model automatically takes over.

The AI prompt instructions and settings are copied exactly from the original project to ensure the same high quality.

What is currently left out (kept simple for now, but planned as optional features later):

  • Web Search / Internet Access in Stage 1: Currently, models answer based on training and context. (Planned as an optional feature in a future release).
  • Editable Prompts / Custom Roles (e.g. Critic mode) in the UI: Prompt templates are currently hardcoded for reliability. (Planned as an optional settings section).
  • Chat History & Interactive Discussion: Currently designed for deep-dive single questions. (An optional discussion mode between Claude and the Chairman to decide which files are needed is planned).
  • Direct File Access: The server does not read your workspace directly for security/simplicity. Your client (Claude Code, Antigravity) reads the files and passes them as parameters.

Installation & Setup

Method A: Quick Onboarding via PyPI (Recommended)

You can run the Setup UI directly from PyPI without cloning the repository (requires the package installer uv to be installed, e.g., via curl -LsSf https://astral.sh/uv/install.sh | sh or brew install uv):

uvx --from llm-council-mcp-server llm-council-setup

This automatically opens http://127.0.0.1:5151 in your browser.

Method B: Manual Clone (for Development)

If you want to modify the source code locally:

git clone https://github.com/salutaris91/llm-council-mcp-server.git
cd llm-council-mcp-server
python3 -m venv venv
source venv/bin/activate

# Install dependencies (either via requirements.txt or directly using pyproject.toml)
pip install -r requirements.txt  # Or: pip install .

Run the Setup UI locally:

python3 setup_ui.py

🚀 Quick Start / First Run

Follow these steps to get up and running:

  1. Launch the Setup UI:
    • Run uvx --from llm-council-mcp-server llm-council-setup in your terminal. This will automatically open the local configuration panel in your web browser.
  2. Configure Settings:
    • For ask_internal_council (Light Mode), no OpenRouter API key is required.
    • For the full ask_council mode, create an API key at openrouter.ai/keys, make sure the account has a small funded balance, paste the key, select your preferred council and Chairman models, and click Save.
  3. Choose Exposed Tools:
    • Keep both tools enabled, or hide one of them if you only want your MCP host to offer the free internal council or the full OpenRouter council.
  4. Register the Server:
    • Under the Install section of the Setup UI, click the Install button next to your desired tool (Claude Code, Codex CLI, or Antigravity).
  5. Restart Your Tool:
    • Fully restart your MCP-enabled editor/client (e.g. reload Antigravity) to apply the changes.
  6. Start Deliberating:
    • In your chat client, run a query (see Usage below).

Setup UI & Settings Storage

The Setup UI provides a user-friendly interface to manage your council settings. It features:

  • Language Switcher: Toggle the UI dynamically between German and English.
  • Model Presets (Quick & Deep): Instantly switch between fast models (for quick checks) and highly capable reasoning models (for deep architectural decisions).
  • Advanced / Expert Settings: Adjust the AI's "creativity" (temperatures) for each of the three stages and configure custom token limits.
  • Tool Visibility Switches: Expose or hide ask_internal_council and ask_council individually. Disabled tools are not offered to the MCP host after restart.
  • Auto-Open Browser Toggle: Choose whether the Setup UI should automatically open your browser on startup.
  • Tool Installer: View the status (Installed/Not Installed) and register/unregister the MCP server in Claude Code, Codex CLI, and Antigravity with a single click.

Your configuration is saved to a settings.json file in your user config directory (e.g., ~/Library/Application Support/llm-council on macOS).
Legacy Note: If you have an existing .env file from manual setups, it will be automatically imported into settings.json on the first start, and can be safely removed afterwards.

Usage

The server exposes two MCP tools:

  1. ask_internal_council (Light Mode):

    • No API Key / No Cost: Runs entirely locally on your host agent's current subscription.
    • How it works: It instantly returns a structured prompt directing your host agent to simulate 5 distinct perspectives (Pragmatist, Architect, Skeptic, Clean Code Advocate, UX Thinker), debate them internally, and synthesize a final recommendation.
    • Note on Diversity: Since all perspectives are simulated by the same single model, the diversity is limited (shared blind spots).

  2. ask_council (Full Mode):

    • Real Multi-Model Consensus: Requires an OpenRouter API key and query costs.
    • How it works: Queries multiple different real AI models in parallel, lets them anonymously review and rank each other, and uses a final Chairman model to synthesize the results. Takes about 30 to 120 seconds.

Ask your MCP host to query the respective tool, passing any code context you want it to evaluate.

Example Prompts:

  • "Use the internal council to analyze whether we should use Redis or Memcached here."
  • "Ask the council to review my implementation of this sorting algorithm."

What happens under the hood (for the full ask_council mode):
The server will run the 3-stage consensus pipeline. Because this involves multiple parallel and sequential LLM calls, the tool response typically takes 30 to 120 seconds to complete. Some hosts (Antigravity) show live progress, others (Codex) only a spinner — the call continues normally and typically takes 30–120 s depending on the models (occasionally a bit longer). Simply wait until the result appears. It will return a formatted Markdown report consisting of the Chairman's synthesis, followed by the individual models' responses and rankings.

Tool Registration (Manual, alternative to Setup UI)

1. If installed via PyPI (Method A)

Claude Code

claude mcp add llm-council --scope user -- uvx --from llm-council-mcp-server llm-council-mcp

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.llm-council]
command = "uvx"
args = ["--from", "llm-council-mcp-server", "llm-council-mcp"]

Antigravity

Add to the configuration file located at ~/.gemini/config/mcp_config.json (do not use ~/.gemini/antigravity/):

{
  "mcpServers": {
    "llm-council": {
      "command": "uvx",
      "args": ["--from", "llm-council-mcp-server", "llm-council-mcp"]
    }
  }
}

2. If cloned manually (Method B)

Replace /path/to/venv/bin/python3 and /path/to/llm-council-mcp/server.py with your absolute paths.

Claude Code

claude mcp add llm-council --scope user -- /path/to/venv/bin/python3 /path/to/llm-council-mcp/server.py

Codex CLI (~/.codex/config.toml)

[mcp_servers.llm-council]
command = "/path/to/venv/bin/python3"
args = ["/path/to/llm-council-mcp/server.py"]

Antigravity (~/.gemini/config/mcp_config.json)

{
  "mcpServers": {
    "llm-council": {
      "command": "/path/to/venv/bin/python3",
      "args": ["/path/to/llm-council-mcp/server.py"]
    }
  }
}

🛠️ Troubleshooting

  • Server not showing up in tool?
    • Fully restart the client application (Claude Code, Codex, or Antigravity). MCP servers are loaded on startup.
  • Antigravity isn't picking up the server?
    • Verify that the server is written to ~/.gemini/config/mcp_config.json. If you manually created a file in ~/.gemini/antigravity/, delete it and use the correct path.
  • OpenRouter API Errors (e.g. 401, 402)?
    • Open the Setup UI and double-check your API key. Make sure your OpenRouter account has positive credit.
  • Check the Logs:
    • Standard error logs are captured by your MCP host. Check your tool's log output or terminal window for details.

Releasing (Maintainer)

This repository is set up with Trusted Publishing to PyPI via GitHub Actions. Releases are triggered tokenless using OIDC.

To release a new version:

  1. Update the version string in _version.py (e.g. 0.2.0). This is the single
    source of truth — pyproject.toml, the installer pin, and the version shown
    in the Setup UI header     all derive from it automatically, so there is no
    separate place to update the displayed version.
  2. Commit and push the changes to main.
  3. Create and push a version tag matching v*.*.*:
    git tag -a v0.2.0 -m "v0.2.0"
git push origin v0.2.0
  4. GitHub Actions will automatically build the package and publish it to PyPI.
  5. Create a GitHub Release referencing the new tag.
  6. Run the Setup UI or installer to update your local configuration file to point to the new version pin.

Credits

Deutsche Version

Inhaltsverzeichnis

Ein schlanker, lokaler MCP-Server für deinen Mac basierend auf der Originalidee von Andrej Karpathy (karpathy/llm-council) mit Prompt-/Workflow-Vorlagen portiert aus DmitryBMsk/llm-council-plus. Er bildet den 3-Stufen-Workflow mit den exakten Original-Prompts direkt gegen OpenRouter nach, ohne Docker- oder NAS-Abhängigkeit. Nutzbar aus Claude Code, Codex CLI und Antigravity über MCP.

Was das ist (und wie es funktioniert)

Dieses Tool bildet den Entscheidungsprozess des Originalprojekts in drei einfachen Schritten ab:

  1. Stufe 1 (Antworten): Mehrere KI-Modelle beantworten deine Frage gleichzeitig und unabhängig voneinander.
  2. Stufe 2 (Bewerten): Die Modelle lesen alle Antworten, ohne zu wissen, welches Modell welche Antwort geschrieben hat (Blindverkostung). Jedes Modell bewertet die Antworten, um Eigenvoreingenommenheit zu verhindern.
  3. Stufe 3 (Zusammenfassen): Ein finales "Chairman"-Modell liest alle Antworten und Bewertungen und verfasst eine ausgewogene Zusammenfassung für dich. Sollte das Chairman-Modell ausfallen, springt automatisch ein anderes Modell ein.

Die KI-Anweisungen (Prompts) und Einstellungen wurden exakt aus dem Originalprojekt übernommen, um die gleiche hohe Qualität der Antworten zu garantieren.

Was aktuell bewusst weggelassen wurde (für maximale Einfachheit – später als optionale Funktionen geplant):

  • Web-Suche / Internetzugriff in Stufe 1: Modelle antworten aktuell basierend auf ihrem Wissen und dem Kontext. (Als optionale Funktion für spätere Releases geplant).
  • Bearbeitbare Prompt-Vorlagen / Eigene Rollen (z. B. Kritiker-Modus) in der UI: Prompt-Vorlagen sind für stabile Ergebnisse fest hinterlegt. (Als optionaler Einstellungsbereich geplant).
  • Chat-Verlauf & Interaktive Diskussion: Aktuell für präzise Einzelanfragen konzipiert. (Ein optionaler Diskussionsmodus zwischen Client und Chairman zur gemeinschaftlichen Ermittlung benötigter Dateien ist geplant).
  • Direkter Dateizugriff: Der Server liest deine Dateien aus Sicherheits- und Einfachheitsgründen nicht selbst. Dein Client (Claude Code, Antigravity) liest den Code aus und übergibt ihn automatisch.

Installation & Setup

Methode A: Schnellstart via PyPI (Empfohlen)

Du kannst die Setup-Oberfläche direkt über PyPI ausführen, ohne das Repository klonen zu müssen (erfordert ein installiertes uv, z. B. installierbar via curl -LsSf https://astral.sh/uv/install.sh | sh oder brew install uv):

uvx --from llm-council-mcp-server llm-council-setup

Dies öffnet automatisch http://127.0.0.1:5151 in deinem Browser.

Methode B: Manueller Klon (für Entwickler)

Wenn du den Quellcode lokal anpassen möchtest:

git clone https://github.com/salutaris91/llm-council-mcp-server.git
cd llm-council-mcp-server
python3 -m venv venv
source venv/bin/activate

# Abhängigkeiten installieren (entweder über requirements.txt oder pyproject.toml)
pip install -r requirements.txt  # Oder: pip install .

Lokale Setup-UI starten:

python3 setup_ui.py

🚀 Schnellstart / Erster Lauf

Befolge diese Schritte, um direkt loszulegen:

  1. Setup-UI starten:
    • Führe uvx --from llm-council-mcp-server llm-council-setup im Terminal aus. Dadurch öffnet sich die lokale Konfigurationsoberfläche in deinem Browser.
  2. Einstellungen konfigurieren:
    • Für ask_internal_council (Light-Modus) brauchst du keinen OpenRouter-API-Key.
    • Für den vollwertigen ask_council-Modus erstellst du einen API-Key auf openrouter.ai/keys, stellst ein kleines Guthaben sicher, trägst den Key ein, wählst deine bevorzugten Council- und Chairman-Modelle und klickst auf Speichern.
  3. Sichtbare Tools wählen:
    • Lass beide Tools aktiv oder blende eines aus, wenn dein MCP-Host nur das kostenlose interne Council oder nur das vollständige OpenRouter-Council anbieten soll.
  4. Server registrieren:
    • Klicke im Bereich Install der Setup-UI auf den Button Install neben dem Tool deiner Wahl (Claude Code, Codex CLI oder Antigravity).
  5. Tool neu starten:
    • Starte deinen MCP-Client / Editor (z. B. Antigravity) komplett neu, um die Registrierung zu laden.
  6. Council anfragen:
    • Stelle deine Frage im Chat-Interface (siehe Nutzung unten).

Setup-UI & Speicherort der Einstellungen

Die Setup-UI bietet eine benutzerfreundliche Oberfläche zur Verwaltung deiner Council-Einstellungen. Zu den Features gehören:

  • Sprachumschalter: Wechselt die UI dynamisch zwischen Deutsch und Englisch.
  • Modell-Presets (Schnell & Deep): Ermöglicht das sofortige Umschalten zwischen schnellen Modellen (für schnelle Checks) und hochentwickelten Reasoning-Modellen (für tiefgehende Architekturfragen).
  • Profi-Modus / Erweiterte Einstellungen: Passe die „Kreativität“ der KI (Temperaturen) für jede der drei Stufen individuell an und definiere maximale Token-Limits.
  • Tool-Sichtbarkeit: ask_internal_council und ask_council einzeln aktivieren oder ausblenden. Deaktivierte Tools werden dem MCP-Host nach Neustart nicht angeboten.
  • Browser Auto-Open Toggle: Wähle aus, ob die Setup-UI beim Start automatisch den Browser öffnen soll.
  • Tool-Installer: Zeigt den aktuellen Installationsstatus an und ermöglicht die Registrierung/Entfernung des MCP-Servers in Claude Code, Codex CLI und Antigravity mit einem Klick.

Deine Konfiguration wird in einer settings.json-Datei im Konfigurationsverzeichnis (z. B. ~/Library/Application Support/llm-council unter macOS) gespeichert.
Migration: Falls noch eine alte .env-Datei aus manuellen Setups vorhanden ist, wird diese beim ersten Start automatisch in die settings.json importiert und kann danach gelöscht werden.

Nutzung

Der Server stellt zwei MCP-Tools bereit:

  1. ask_internal_council (Light-Modus):

    • Kein API-Key / Kostenlos: Läuft vollständig lokal über das aktuelle Abo deines Host-Agenten.
    • Funktionsweise: Liefert sofort einen strukturierten Prompt zurück, der deinen Host-Agenten anweist, 5 verschiedene Sichtweisen (Pragmatiker, Architekt, Skeptiker, Clean-Code-Verfechter, UX-Optimierer) einzunehmen, diese intern zu debattieren und eine finale Synthese zu schreiben.
    • Diversitäts-Hinweis: Da alle Sichtweisen von ein und demselben Modell simuliert werden, ist die gedankliche Diversität durch die blinden Flecken des Modells eingeschränkt.

  2. ask_council (Vollwertiger Modus):

    • Echter Multi-Modell-Konsens: Benötigt einen OpenRouter-API-Key und verursacht API-Kosten.
    • Funktionsweise: Fragt parallel mehrere echte Modelle an, lässt sie sich gegenseitig anonym bewerten und nutzt ein Chairman-Modell zur Synthese. Ein Durchlauf dauert ca. 30 bis 120 Sekunden.

Bitte deinen MCP-Client einfach darum, das gewünschte Tool aufzurufen und übergib die Frage sowie den zu prüfenden Code.

Beispiel-Prompts:

  • "Nutze das interne Council, um eine zweite Meinung dazu zu bekommen, ob wir hier Redis oder Memcached nehmen sollten."
  • "Frag das echte Council nach einem Review für meine Implementierung dieses Sortieralgorithmus."

Was im Hintergrund passiert (beim vollwertigen ask_council-Modus):
Der Server führt die 3 Stufen des Council-Prozesses durch. Da dies mehrere parallele und sequenzielle LLM-Aufrufe erfordert, dauert die Antwort in der Regel 30 bis 120 Sekunden. Manche Hosts (Antigravity) zeigen Live-Fortschritt, andere (Codex) nur einen Spinner — der Call läuft dabei ganz normal weiter und dauert je nach Modellen typischerweise 30–120 s (gelegentlich etwas länger). Einfach warten, bis das Ergebnis erscheint. Du erhältst einen formatierten Markdown-Report mit der Synthese des Chairmans, gefolgt von den Antworten der Einzelmodelle sowie deren Rankings.

Tool-Registrierung (Manuell, alternativ zur Setup-UI)

1. Bei Installation via PyPI (Methode A)

Claude Code

claude mcp add llm-council --scope user -- uvx --from llm-council-mcp-server llm-council-mcp

Codex CLI

Trage Folgendes in ~/.codex/config.toml ein:

[mcp_servers.llm-council]
command = "uvx"
args = ["--from", "llm-council-mcp-server", "llm-council-mcp"]

Antigravity

Trage Folgendes in die Konfigurationsdatei unter ~/.gemini/config/mcp_config.json ein (nutze nicht ~/.gemini/antigravity/):

{
  "mcpServers": {
    "llm-council": {
      "command": "uvx",
      "args": ["--from", "llm-council-mcp-server", "llm-council-mcp"]
    }
  }
}

2. Bei manuellem Klon (Methode B)

Ersetze /pfad/zu/venv/bin/python3 und /pfad/zu/llm-council-mcp/server.py mit deinen absoluten Pfaden.

Claude Code

claude mcp add llm-council --scope user -- /pfad/zu/venv/bin/python3 /pfad/zu/llm-council-mcp/server.py

Codex CLI (~/.codex/config.toml)

[mcp_servers.llm-council]
command = "/pfad/zu/venv/bin/python3"
args = ["/pfad/zu/llm-council-mcp/server.py"]

Antigravity (~/.gemini/config/mcp_config.json)

{
  "mcpServers": {
    "llm-council": {
      "command": "/pfad/zu/venv/bin/python3",
      "args": ["/pfad/zu/llm-council-mcp/server.py"]
    }
  }
}

🛠️ Fehlerbehebung

  • Server erscheint nicht im Tool?
    • Starte die Client-Anwendung (Claude Code, Codex oder Antigravity) komplett neu. MCP-Server werden beim Start geladen.
  • Antigravity erkennt den Server nicht?
    • Überprüfe, ob der Server-Eintrag in ~/.gemini/config/mcp_config.json steht. Falls du manuell eine Datei in ~/.gemini/antigravity/ angelegt hast, lösche diese und nutze den korrekten Pfad.
  • Fehler beim Aufruf von OpenRouter (z. B. 401, 402)?
    • Öffne die Setup-UI und kontrolliere deinen API-Key. Vergewissere dich, dass dein OpenRouter-Konto über ausreichend Guthaben verfügt.
  • Logs einsehen:
    • Fehlermeldungen werden von deinem MCP-Client erfasst. Siehe in den Logs des Editors oder im Terminalfenster nach Details.

Releasing (Maintainer)

Dieses Repository verwendet Trusted Publishing über GitHub Actions, um Releases vollautomatisch auf PyPI zu veröffentlichen. Das Publishing erfolgt tokenlos mittels OIDC.

Ablauf für ein neues Release:

  1. Versionsnummer in _version.py anpassen (z. B. 0.2.0).
  2. Änderungen committen und auf main pushen.
  3. Versions-Tag erstellen und pushen (muss auf v*.*.* passen):
    git tag -a v0.2.0 -m "v0.2.0"
git push origin v0.2.0
  4. GitHub Actions baut und veröffentlicht das Paket automatisch auf PyPI.
  5. Ein GitHub-Release für den neuen Tag erstellen.
  6. Die Setup-UI oder den Installer ausführen, um die lokale Konfigurationsdatei auf den neuen Versions-Pin zu aktualisieren.

Credits

Reviews (0)

No results found