Veilleur

Veilleur — Discord 用 MCP サーバー

英語版

Veilleur は、AI で Discord サーバーを管理するための MCP（Model Context Protocol）サーバーです。ローカルで動作し、Discord ボットを通じてチャンネルの作成、ロールの変更、埋め込みメッセージの送信などを行います。

仕組みは、AI に希望を伝えると、AI が変更内容を準備し、適用前にあなたが承認するというものです。何をするかわからないまま、サーバーの鍵をAIに渡さずに済みます。

このプロジェクトはAIの助けを借りて作成しました。

どのように動作しますか？

たとえば、次のように依頼できます。

「Accueil」カテゴリを作成し、読み取り専用のルールと「Modérateur」ロールを設定してください。

AI が実行予定の操作を表示します。内容に問題がなければ、PC にウィンドウが開きます。チェックボックスにチェックを入れて承認すると、Veilleur がサーバー構成を保存し、AI が変更を実行します。

結果が気に入らなければ、変更を元に戻すよう依頼できます。**注意：完全な Ctrl+Z ではありません。**削除したチャンネルは再作成できますが、メッセージは失われ、新しい ID が割り当てられます。詳しくはバックアップをご覧ください。

できること

• チャンネル、カテゴリ、ロールの作成、変更、削除、および権限の管理。
• ロールの付与と削除、メンバーの検索、ニックネームの変更、タイムアウトの管理。
• メッセージや埋め込みメッセージの送信、およびボットが送信したメッセージの編集。
• 複数の操作のグループ化、構成のバックアップ、変更を元に戻す準備。

ボットには対応する Discord 権限が必要です。また、自身のロールより下にあるロールのみ管理できます。Discord サーバーはあらかじめ作成しておく必要があります。

インストール

1. 前提条件

• Windows、Python 3.11、およびランチャー py。承認用インターフェイスでは Tkinter を使用します。通常、Tkinter は Python に含まれています。
• ボットを招待できる Discord サーバー。
• Codex など、stdio での MCP サーバーに対応した AI クライアント。
• インターネット接続。プログラムは PC 上で動作しますが、Discord との通信が必要です。

2. ボットの作成

1. Discord 開発者ポータルでアプリケーションを作成します。
2. Bot タブでトークンを生成し、後で使えるように保管します。どこにも投稿しないでください。
3. OAuth2 → URL Generator で bot と必要な権限を選択し、リンクを開いてボットを招待します。
4. サーバーの Discord 設定で、ボットのロールを管理対象のロールより上に配置します。
5. Discord で開発者モードを有効にし、サーバーを右クリックして サーバー ID をコピーします。

3. Veilleur の設定

リポジトリをダウンロードまたはクローンし、そのフォルダーで PowerShell を開きます。

Set-ExecutionPolicy -Scope Process Bypass
.\installer.ps1

インストーラーは、Python 環境と .env および config.json を、まだ存在しない場合に作成します。

.env を開き、= の後にトークンを入力します。

DISCORD_BOT_TOKEN=ton_token

config.json で、サーバー ID を引用符で囲んで入力します。

{
  "guild_id": "123456789012345678"
}

これらのファイルは Git の対象外です。トークンが漏えいした場合は、Discord ポータルで再生成してください。

4. AI クライアントを接続する

Codex の場合は、プロジェクトフォルダーで次のコマンドを実行します。

$pythonDiscord = (Resolve-Path .\.venv\Scripts\python.exe).Path
$serveurDiscord = (Resolve-Path .\server.py).Path
codex mcp add discord-local -- $pythonDiscord $serveurDiscord

Codex を再起動してから、「Discord サーバーを読み込んで、整理方法を提案して」と試してみてください。discord-local がすでにこれらのパスで設定されている場合は、再度追加する必要はありません。

OpenCode v2 の場合は、プロジェクトをインストールし、.env と config.json を設定した後、リポジトリフォルダーで次のコマンドを実行します。

$pythonDiscord = (Resolve-Path .\.venv\Scripts\python.exe).Path
$serveurDiscord = (Resolve-Path .\server.py).Path
opencode mcp add veilleur --global -- $pythonDiscord $serveurDiscord
opencode mcp list

設定はグローバルに適用されるため、Veilleur は OpenCode のプロジェクトから利用できます。必要に応じて OpenCode を再起動してください。接続は OpenCode v2.1.4 とテスト用設定で検証済みです。他のバージョンについては、OpenCode のドキュメントを参照してください。

Claude Code の場合は、.env と config.json を設定した後、リポジトリフォルダーで次のコマンドを実行します。

$pythonDiscord = (Resolve-Path .\.venv\Scripts\python.exe).Path
$serveurDiscord = (Resolve-Path .\server.py).Path
claude mcp add --scope user --transport stdio veilleur -- $pythonDiscord $serveurDiscord
claude mcp list

この設定は Claude Code のプロジェクトで利用できます。Claude Desktop のチャット設定とは別のものです。接続は Claude Code 2.1.226 とテスト用設定で検証済みです。Claude Code のドキュメントを参照してください。

stdio に対応する他の MCP クライアントでは、.venv\Scripts\python.exe の絶対パスをコマンドとして、server.py の絶対パスを引数として使用してください。設定方法はクライアントによって異なります。検証ウィンドウを Windows のセッションで開ける必要があります。

pip を使ったインストール

Veilleur は PyPI と公式 MCP レジストリで公開されています。レジストリで io.github.NoPaperSpray/veilleur を検索してください。

Windows では、専用の環境にパッケージをインストールできます。

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install veilleur-discord-mcp

MCP クライアントでは、.venv\Scripts\veilleur-discord-mcp.exe の絶対パスをコマンドとして使用し、ローカル設定で環境変数 DISCORD_BOT_TOKEN と DISCORD_GUILD_ID を指定してください。トークンは非公開にしてください。一部のクライアントでは、この設定が平文で保存されます。

この方法でインストールした場合、プランとバックアップはデフォルトで %LOCALAPPDATA%\Veilleur に保存されます。VEILLEUR_HOME を使って別のフォルダーを指定できます。リポジトリのコピーでは、python -m pip install . でもパッケージをインストールできます。従来のコマンド python server.py は引き続き、リポジトリフォルダー内の .env、config.json、data/ を使用します。そのバックアップは、インストールしたパッケージのバックアップとは別に保存されます。

検証とバックアップ

プランを実行するには、事前にローカルウィンドウで承認する必要があります。承認はそのプランに限り、10 分間有効で、実行は 1 回のみです。その間にサーバーまたは対象が変わった場合は、新しいプランを準備する必要があります。

実行前に Veilleur は、構造、ロール、一部の設定、そして直接関係するメンバーやメッセージをバックアップします。ファイルは data/ に保存され、個人情報が含まれる場合があります。

バックアップの範囲は、ボットが閲覧できる内容によって異なります。アクセスできないチャンネルは含まれない場合があります。復元を前提にする前に、ボットの権限を確認してください。

復元には制限があります。再作成された項目には新しい ID が割り当てられます。削除されたメッセージ、添付ファイル、リアクションは復元されません。外部リンク、スレッド、招待、インテグレーションは自動的に修復されません。また、削除されたロールの割り当ては、すべてのメンバーについてバックアップされるわけではありません。

ロールバックにもプレビューが必要で、バックアップ後に行われた変更が上書きされることがあります。エラーが発生した場合や、ネットワーク応答が失われた場合は、再実行する前にログを確認してください。

検証が適用されるのは、Veilleur の MCP ツールです。ファイルや Discord アカウントにアクセスできるプログラムからトークンを保護するものではありません。

トラブルシューティング

• クライアントにVeilleurが表示されない：Pythonとserver.pyのパスを確認してから、クライアントを再起動してください。
• ウィンドウが開かない：AIにプランIDを尋ねてから、プロジェクトフォルダーで.\.venv\Scripts\python.exe approve.py ID_DU_PLANを実行してください。
• 401エラー：.envのトークンを確認してください。
• 403エラー：ボットの権限とロールの位置を確認してください。メンバーの検索やメッセージの読み取りには、Discordポータルでインテントの設定が必要な場合もあります。
• ボットがオフラインになっている：これは正常です。VeilleurはGatewayに接続せず、HTTP APIを使用します。

AIにdiagnosticの実行を依頼することもできます。サーバーレベルでボットの接続と権限を確認します。各チャンネル固有の例外は判定しません。

詳しくは、完全なマニュアルとAI向けツールガイドをご覧ください。

テスト

テストはオフラインで実行され、トークンは使用しません：

.\.venv\Scripts\python.exe -m unittest discover -v

プログラムを更新した後は、MCPクライアントを再起動して、新しいバージョンを読み込んでください。

貢献

バグやアイデアがありますか？Issueを作成してください。コードを提案する場合は、CONTRIBUTING.mdをご覧ください。プロジェクトはMITライセンスの下で公開されています。