MCP CLI - Model Context Protocol Command Line Interface

Name: MCP CLI - Model Context Protocol Command Line Interface
Author: chrishayuk

github.com/chrishayukフレームワーク・SDK2.0k13 週間前に更新

MCP CLI - Model Context Protocol Command Line Interface について

MCP CLI は、Model Context Protocol サーバーと対話するためのコマンドラインクライアントです。CHUK Tool Processor と CHUK-LLM を基盤としています。既定ではローカルの Ollama 推論モデルを使用し、チャット、対話、コマンド、直接実行の各モードに対応します。

主な機能

01チャット、対話、コマンド、直接実行の 4 つのモード
02Ollama、OpenAI、Anthropic などの複数プロバイダー対応
03リトライとサーキットブレーカーを備えた並行ツール実行
04DAG 可視化を伴う実行プラン
05会話コンテキストを管理する実験的な仮想メモリ
06マルチモーダル添付と会話のエクスポート

活用シーン

01ローカルの Ollama モデルと対話し、MCP ツールを呼び出す
02コマンドモードでMCP ツールの呼び出しをパイプラインに組み込む
03実行プランで複数段階のツール呼び出しを編成する

MCP 対応

MCP CLI は MCP クライアントとして MCP サーバーに接続し、提供されるツールを検出して LLM から利用できるようにします。OAuth 認証やサーバーのヘルスチェックも扱います。

詳細

MCP CLI - Model Context Protocol コマンドラインインターフェース

Model Context Protocol サーバーとやり取りするための、強力で機能豊富なコマンドラインインターフェースです。このクライアントは、CHUK Tool Processor および CHUK-LLM との統合を通じて LLM とのシームレスな通信を実現し、ツールの使用、会話の管理、複数の動作モードを提供します。

デフォルト設定：MCP CLI は、API キーを必要とせず、ローカルでプライバシーを重視した運用を行えるよう、デフォルトで Ollama と gpt-oss 推論モデルを使用します。

🆕 最近の更新（v0.16）

AI 仮想メモリ（実験的）

--vm フラグ：chuk-ai-session-manager を利用して、会話コンテキスト管理に OS 形式の仮想メモリを有効にします
--vm-budget：会話イベントのトークン予算を制御します（システムプロンプトには別途上限がありません）。これにより、より早い退避とページ作成が促されます
--vm-mode：VM モードを選択します — passive（ランタイム管理、デフォルト）、relaxed（VM を考慮した会話）、strict（ツールを使ったモデル主導のページング）
/memory コマンド：会話中に VM の状態を可視化します — ページテーブル、ワーキングセット使用率、退避メトリクス、TLB 統計（エイリアス：/vm、/mem）
マルチモーダルな page_fault：画像ページは複数ブロックのコンテンツ（テキスト + image_url）を返すため、マルチモーダルモデルは呼び出し直した画像を再分析できます
/memory page <id> --download：ページのコンテンツを、モダリティに応じた拡張子（.txt、.json、.png）のローカルファイルにエクスポートします

実行プラン（Tier 6）

/plan コマンド：再現可能なツール呼び出しグラフを作成、確認、実行します — create、list、show、run、delete、resume
モデル主導のプランニング（--plan-tools）：LLM が会話中に自律的にプランを作成して実行するため、/plan コマンドは不要です。複数ステップのオーケストレーションが必要な場合は plan_create_and_execute を呼び出し、単純なタスクには通常のツールを使用します。各ステップの進行状況はターミナルにリアルタイムで表示されます
並列バッチ実行：独立したプランのステップを、トポロジカルなバッチ処理（Kahn の BFS）によって並行実行します。max_concurrency を設定できます
変数の解決：${var}、${var.field} によるネストしたアクセス、および "https://${api.host}/users" のようなテンプレート文字列に対応します — 単一参照では型が保持されます
ドライランモード：実行せずに、予定されているツール呼び出しを追跡します — 本番環境の確認も安全に行えます
チェックポイントと再開：各バッチの後に実行状態が永続化されます。中断したプランは /plan resume <id> で再開できます
ガードとの統合：プランは既存の予算、ツールごとの制限、暴走検出ガードに従います
DAG の可視化：状態インジケーター（○/◉/●/✗）と並列マーカー（∥）を使って ASCII 形式で表示します
再プランニング：ステップの失敗時に、オプションで LLM による再プランニングを行います（enable_replan=True）
提供元：chuk-ai-planner のグラフベースのプラン DSL

MCP Apps（SEP-1865）

インタラクティブな HTML UI：MCP サーバーは、ブラウザーで表示するインタラクティブな HTML アプリケーション（チャート、テーブル、マップ、Markdown ビューアー）を提供できます
サンドボックス化された iframe：アプリは CSP 保護された安全なサンドボックス内の iframe で実行されます
WebSocket ブリッジ：ブラウザーアプリと MCP サーバー間のリアルタイムな双方向通信
自動起動：_meta.ui アノテーションが付いたツールは、呼び出されるとブラウザーで自動的に開きます
セッションの信頼性：メッセージキューイング、指数バックオフによる再接続、ツール結果の遅延配信

本番環境向けの強化

シークレットのマスキング：すべてのログ出力（コンソールとファイル）で、Bearer トークン、API キー、OAuth トークン、Authorization ヘッダーを自動的にマスキングします
構造化ファイルロギング：オプションの --log-file フラグを有効にすると、DEBUG レベルのローテーション対応 JSON ログファイル（10MB、バックアップ 3 個）が生成されます
サーバーごとのタイムアウト：サーバー設定で tool_timeout と init_timeout の上書きをサポートし、サーバーごと → グローバル → デフォルトの順に適用されます
スレッドセーフな OAuth：asyncio.Lock とコピーオンライト方式のヘッダー変更により、並行する OAuth フローを直列化します
サーバーのヘルスモニタリング：/health コマンド、失敗時のヘルスチェック診断、オプションの --health-interval によるバックグラウンドポーリングを提供します

パフォーマンスと仕上げ

O(1) のツール検索：O(n) の線形検索をインデックス付きツール検索に置き換えます
LLM ツールメタデータのキャッシュ：プロバイダーごとにキャッシュし、自動的に無効化します
起動時の進行状況表示：初期化中に進行状況メッセージをリアルタイムで表示します
トークン使用量の追跡：/usage コマンド（別名：/tokens、/cost）で、ターンごとおよび累積の使用量を追跡します
セッションの永続化：会話セッションの保存、読み込み、一覧表示に対応し、10 ターンごとに自動保存します（/sessions）
会話のエクスポート：メタデータを含めて、会話を Markdown または JSON としてエクスポートします（/export）

ダッシュボード（リアルタイムのブラウザー UI）

--dashboard フラグ：チャットモードと並行して、リアルタイムのブラウザーダッシュボードを起動します
エージェントターミナル：メッセージバブル、ストリーミングトークン、添付ファイルの表示に対応した、会話のライブビューです
アクティビティストリーム：ツール呼び出しと結果のペア、推論ステップ、ユーザー添付ファイルのイベントを表示します
プランビューアー：DAG 表示を使って、実行プランの進行状況を視覚的に表示します
ツールレジストリ：検出されたツールを参照し、ブラウザーから実行できます
設定パネル：プロバイダー、モデル、システムプロンプトを表示し、切り替えられます
ファイル添付：ブラウザーからのファイルアップロード、ドラッグ＆ドロップ、クリップボードからの貼り付けに対応した「+」ボタンを提供します

マルチモーダル添付ファイル

/attach コマンド：次のメッセージに添付するファイル（画像、テキスト／コード、音声）を準備します（別名：/file、/image）
--attach CLI フラグ：最初のメッセージにファイルを添付します（繰り返し指定可能：--attach img.png --attach code.py）
インラインの @file: 参照：メッセージ内の任意の場所で @file:path/to/file を指定すると、そのファイルを添付します
画像 URL の検出：メッセージ内の HTTP/HTTPS 画像 URL は、ビジョンコンテンツとして自動的に送信されます
対応形式：PNG、JPEG、GIF、WebP、HEIC（画像）、MP3、WAV（音声）、および 25 種類以上のテキスト／コード拡張子
ダッシュボードでの表示：画像サムネイル、展開可能なテキストプレビュー、オーディオプレーヤー、ファイルバッジに対応します
ブラウザーからのアップロード：ダッシュボードのチャット入力欄にある「+」ボタンから、ドラッグ＆ドロップやクリップボードからの貼り付けを利用できます

コード品質

コアと UI の分離：コアモジュールでは logging のみを使用し、UI をインポートしません
4,300 件以上のテスト：分岐網羅率、統合テスト、最低 60% のしきい値を備えた包括的なテストスイートです
15 のアーキテクチャ原則：文書化され、遵守が徹底されています（architecture.md を参照）
完全なロードマップ：Tier 1～6 は完了、Tier 7～12 は計画中です（トレース、メモリスコープ、スキル、スケジューリング、マルチエージェント）

🔄 アーキテクチャの概要

MCP CLI は、責務を明確に分離したモジュール型アーキテクチャを基盤としています。

CHUK Tool Processor：ミドルウェア（リトライ、サーキットブレーカー、レート制限）、複数の実行方式、オブザーバビリティを備えた、本番環境向けの非同期ツール実行機能を提供します
CHUK-LLM：動的なモデル検出、機能ベースの選択、llama.cpp 統合を備えた統合 LLM プロバイダーです（自動的なモデル再利用により、Ollama より 1.53 倍高速です）
CHUK-Term：テーマ、クロスプラットフォームのターミナル管理、リッチな書式設定を備えた強化版ターミナル UI です
MCP CLI：コマンドのオーケストレーションと統合レイヤーです（このプロジェクト）

🌟 機能

複数の操作モード

チャットモード：ストリーミング応答とツールの自動使用に対応した会話型インターフェース（デフォルト：Ollama/gpt-oss）
インタラクティブモード：サーバーを直接操作するコマンド駆動型シェルインターフェース
コマンドモード：スクリプトによる自動化やパイプラインに適した、Unix フレンドリーなモード
直接コマンド：インタラクティブモードに入らずに個別のコマンドを実行

高度なチャットインターフェース

ストリーミング応答：ライブ UI の更新を伴うリアルタイムの応答生成
推論の可視化：推論モデル（gpt-oss、GPT-5、Claude 4.5）の AI の思考プロセスを確認
ツールの同時実行：会話の順序を保ちながら複数のツールを同時に実行
スマートな中断：Ctrl+C でストリーミング応答やツールの実行を中断
パフォーマンス指標：応答時間、1 秒あたりの単語数、実行統計
リッチな書式設定：Markdown のレンダリング、構文のハイライト、進行状況インジケーター
トークン使用量の追跡：/usage コマンドでターンごとおよび累積の API トークン使用量を確認
マルチモーダル添付：/attach、--attach、@file: 参照、またはブラウザーからのアップロードで、画像、テキストファイル、音声をメッセージに添付
セッションの永続化：会話セッションの自動保存と手動での保存／読み込み
会話のエクスポート：メタデータとトークン使用量を含めて、Markdown または JSON にエクスポート

包括的なプロバイダーサポート

MCP CLI は、最先端の推論モデルを含む、CHUK-LLM のすべてのプロバイダーとモデルをサポートしています：

プロバイダー	主なモデル	特別な機能
Ollama（デフォルト）	🧠 gpt-oss、llama3.3、llama3.2、qwen3、qwen2.5-coder、deepseek-coder、granite3.3、mistral、gemma3、phi3、codellama	ローカル推論モデル、プライバシー重視、API キー不要
OpenAI	🚀 GPT-5 ファミリー（gpt-5、gpt-5-mini、gpt-5-nano）、GPT-4o ファミリー、O3 シリーズ（o3、o3-mini）	高度な推論、関数呼び出し、ビジョン
Anthropic	🧠 Claude 4.5 ファミリー（claude-4-5-opus、claude-4-5-sonnet）、Claude 3.5 Sonnet	強化された推論、長いコンテキスト
Azure OpenAI 🏢	エンタープライズ向け GPT-5、GPT-4 モデル	プライベートエンドポイント、コンプライアンス、監査ログ
Google Gemini	Gemini 2.0 Flash、Gemini 1.5 Pro	マルチモーダル、高速な推論
Groq ⚡	Llama 3.1 モデル、Mixtral	超高速な推論（500+ トークン／秒）
Perplexity 🌐	Sonar モデル	出典付きのリアルタイムウェブ検索
IBM watsonx 🏢	Granite、Llama モデル	エンタープライズコンプライアンス
Mistral AI 🇪🇺	Mistral Large、Medium	欧州製、効率的なモデル

堅牢なツールシステム（CHUK Tool Processor v0.22+ による）

自動検出：サーバーが提供するツールを自動的に検出してカタログ化
プロバイダーへの適応：プロバイダーとの互換性を確保するため、ツール名を自動的にサニタイズ
本番環境品質の実行：タイムアウト、再試行、指数バックオフ、キャッシュ、サーキットブレーカーを備えたミドルウェア層
複数の実行戦略：プロセス内（高速）、分離されたサブプロセス（安全）、または MCP 経由のリモート実行
同時実行：適切な連携のもと、複数のツールを同時に実行可能
詳細な進行状況表示：リアルタイムの進行状況インジケーターと実行時間
ツール履歴：すべてのツール実行の完全な監査証跡
ミドルウェア：CTP による指数バックオフ付き再試行、サーキットブレーカー、レート制限
ストリーミングツール呼び出し：ストリーミングデータを返すツールをサポート

MCP アプリ（インタラクティブ UI）

ブラウザベースの UI: MCP サーバーは、ブラウザでレンダリングされるインタラクティブな HTML アプリケーションを提供できます
自動検出: _meta.ui アノテーションを持つツールは、ツール呼び出し時にブラウザアプリを自動的に起動します
サンドボックス化された実行: アプリは、Content Security Policy 保護を備えた安全なサンドボックス化された iframe 内で実行されます
WebSocket ブリッジ: ブラウザアプリと MCP ツールサーバー間のリアルタイム JSON-RPC ブリッジ
セッションの永続化: 切断中のメッセージキューイング、自動再接続、遅延されたツール結果の配信
structuredContent サポート: 構造化コンテンツの抽出と転送を含む、MCP 仕様への完全準拠

実行プラン（chuk-ai-planner による提供）

プランの作成: LLM ベースのプランエージェントを使用して、自然言語の説明から実行プランを生成します
モデル駆動型プランニング: --plan-tools を指定すると、LLM がいつプランを立てるかを自律的に決定します — 複雑なマルチステップタスクでは plan_create_and_execute を呼び出し、単純なタスクでは通常のツールを使用します
DAG 実行: プランは有向非巡回グラフです — 独立したステップは並列バッチで実行され、依存するステップは待機します
変数の解決: ステップの出力は変数（result_variable）にバインドされ、後続のステップから ${var} または ${var.field} として参照されます
ドライランモード: ツールを一切実行せずに、プランが何を行うかをトレースします — 本番環境でも安全です
チェックポイント: 各バッチの後に実行状態が保存されます。中断されたプランは、完了済みのステップを再実行せずに再開できます
ガードの統合: プランは会話と予算およびツールごとの制限を共有します — バイパスはできません
再プランニング: ステップが失敗した場合、オプションで LLM を呼び出し、残りの作業に対する修正済みプランを生成します
DAG の可視化: ASCII レンダリングで依存関係の構造、バッチのグループ化、並列マーカーを表示します
永続化: プランは ~/.mcp-cli/plans/ に JSON として保存されます

高度な設定管理

環境変数の統合: 環境変数を介した API キーと設定
ファイルベースの設定: YAML および JSON 設定ファイル
ユーザー設定: アクティブなプロバイダーとモデルの永続的な設定
検証と診断: 組み込みのプロバイダーヘルスチェックと設定の検証

強化されたユーザーエクスペリエンス

クロスプラットフォーム対応: chuk-term によるプラットフォーム固有の最適化を備えた Windows、macOS、Linux
リッチなコンソール出力: 8 つの組み込みテーマ（default、dark、light、minimal、terminal、monokai、dracula、solarized）を備えた chuk-term による提供
高度なターミナル管理: クリア、リサイズ、色検出、カーソル制御を含むクロスプラットフォームのターミナル操作
インタラクティブな UI コンポーネント: chuk-term のプロンプトシステム（ask、confirm、select_from_list、select_multiple）によるユーザー入力の処理
コマンド補完: すべてのインターフェースに対するコンテキスト対応のタブ補完
包括的なヘルプ: 例と使用パターンを備えた詳細なヘルプシステム
優雅なエラー処理: トラブルシューティングのヒントを含むユーザーフレンドリーなエラーメッセージ

📚 ドキュメント

包括的なドキュメントは docs/ ディレクトリで利用できます:

プロジェクト

アーキテクチャ - 15 の設計原則、モジュール構成、コーディング規約
ロードマップ - ビジョン、完了したティア（1〜5）、計画中のティア（6〜12: プラン、トレース、スキル、スケジューリング、マルチエージェント、リモートセッション）

コアドキュメント

コマンドシステム - 統合コマンドシステムの完全ガイド、パターン、すべてのモードでの使用方法
トークン管理 - OAuth、ベアラートークン、API キーを含む、プロバイダーとサーバーのための包括的なトークン管理

専門ドキュメント

実行計画 - 計画の作成、並列実行、変数の解決、チェックポイント、ガード、再計画
ダッシュボード - エージェントのターミナル、アクティビティストリーム、ファイルアップロード機能を備えたリアルタイムのブラウザー UI
添付ファイル - 画像、テキスト、音声、ブラウザーからのアップロードに対応したマルチモーダルなファイル添付
MCP アプリ - MCP サーバーが提供するインタラクティブなブラウザー UI（SEP-1865）
OAuth 認証 - OAuth フロー、ストレージバックエンド、MCP サーバーとの統合
ストリーミング統合 - リアルタイムの応答ストリーミングアーキテクチャ
パッケージ管理 - 依存関係の構成と機能グループ

UI ドキュメント

テーマ - テーマシステムとカスタマイズ
出力システム - リッチなコンソール出力と書式設定
ターミナル管理 - クロスプラットフォームのターミナル操作

テストドキュメント

ユニットテスト - テストの構成とパターン
テストカバレッジ - カバレッジ要件とレポート

📋 前提条件

Python 3.11 以降
ローカルで実行する場合（デフォルト）：
- Ollama：ollama.ai からインストールします
- デフォルトの推論モデルを取得します：ollama pull gpt-oss
クラウドプロバイダーを利用する場合（任意）：
- OpenAI：環境変数 OPENAI_API_KEY（GPT-5、GPT-4、O3 モデル用）
- Anthropic：環境変数 ANTHROPIC_API_KEY（Claude 4.5、Claude 3.5 用）
- Azure：AZURE_OPENAI_API_KEY と AZURE_OPENAI_ENDPOINT（エンタープライズ向け GPT-5 用）
- Google：GEMINI_API_KEY（Gemini モデル用）
- Groq：GROQ_API_KEY（高速な Llama モデル用）
- カスタムプロバイダー：プロバイダー固有の設定
MCP サーバー：サーバー設定ファイル（デフォルト：server_config.json）

🚀 インストール

Ollama でクイックスタート（デフォルト）

Ollama をインストールします（まだインストールしていない場合）：

# macOS/Linux
curl -fsSL https://ollama.ai/install.sh | sh

# Or visit https://ollama.ai for other installation methods

デフォルトの推論モデルを取得します：

ollama pull gpt-oss  # Open-source reasoning model with thinking visibility

MCP CLI をインストールして実行します：

# Using uvx (recommended)
uvx mcp-cli --help

# Or install from source
git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli
pip install -e "."
mcp-cli --help

# Optional: Enable MCP Apps (interactive browser UIs)
pip install -e ".[apps]"

別のモデルを使用する

# === LOCAL MODELS (No API Key Required) ===

# Use default reasoning model (gpt-oss)
mcp-cli --server sqlite

# Use other Ollama models
mcp-cli --model llama3.3              # Latest Llama
mcp-cli --model qwen2.5-coder         # Coding-focused
mcp-cli --model deepseek-coder        # Another coding model
mcp-cli --model granite3.3            # IBM Granite

# === CLOUD PROVIDERS (API Keys Required) ===

# GPT-5 Family (requires OpenAI API key)
mcp-cli --provider openai --model gpt-5          # Full GPT-5 with reasoning
mcp-cli --provider openai --model gpt-5-mini     # Efficient GPT-5 variant
mcp-cli --provider openai --model gpt-5-nano     # Ultra-lightweight GPT-5

# GPT-4 Family
mcp-cli --provider openai --model gpt-4o         # GPT-4 Optimized
mcp-cli --provider openai --model gpt-4o-mini    # Smaller GPT-4

# O3 Reasoning Models
mcp-cli --provider openai --model o3             # O3 reasoning
mcp-cli --provider openai --model o3-mini        # Efficient O3

# Claude 4.5 Family (requires Anthropic API key)
mcp-cli --provider anthropic --model claude-4-5-opus    # Most advanced Claude
mcp-cli --provider anthropic --model claude-4-5-sonnet  # Balanced Claude 4.5
mcp-cli --provider anthropic --model claude-3-5-sonnet  # Claude 3.5

# Enterprise Azure (requires Azure configuration)
mcp-cli --provider azure_openai --model gpt-5    # Enterprise GPT-5

# Other Providers
mcp-cli --provider gemini --model gemini-2.0-flash      # Google Gemini
mcp-cli --provider groq --model llama-3.1-70b          # Fast Llama via Groq

🧰 グローバル設定

デフォルト設定

MCP CLI のデフォルト設定は次のとおりです：

プロバイダー：ollama（ローカル、API キー不要）
モデル：gpt-oss（思考過程を確認できるオープンソースの推論モデル）

コマンドライン引数

すべてのモードとコマンドで使用できるグローバルオプション：

--server：接続するサーバーを指定します（カンマ区切り）
--config-file：サーバー設定ファイルのパス（デフォルト：server_config.json）
--provider：LLM プロバイダー（デフォルト：ollama）
--model：使用するモデル（Ollama の場合のデフォルト：gpt-oss）
--disable-filesystem：ファイルシステムへのアクセスを無効にします（デフォルト：有効）
--api-base：API エンドポイント URL を上書きします
--api-key：API キーを上書きします（Ollama では不要）
--token-backend：トークンの保存先バックエンドを上書きします（auto、keychain、windows、secretservice、encrypted、vault）
--verbose：詳細なログ記録を有効にします
--quiet：必須ではない出力を抑制します
--log-file：デバッグログをローテーションするファイルに書き込みます（シークレットは自動的にマスキングされます）
--vm：[実験的] コンテキスト管理用の AI 仮想メモリを有効にします
--vm-budget：VM モードで会話イベントに使用するトークン予算（デフォルト：128000、システムプロンプトの分は含みません）
--vm-mode：VM モード — passive（デフォルト）、relaxed、または strict
--dashboard：チャットモードとともにリアルタイムのブラウザーダッシュボード UI を起動します
--attach：最初のメッセージにファイルを添付します（繰り返し指定可能：--attach img.png --attach code.py）
--plan-tools：モデル主導の計画を有効にします — LLM が自律的に複数ステップの計画を作成して実行します
--no-tools：MCP ツール呼び出しを完全に無効にします — MCP サーバーに接続せず、LLM と直接チャットします

環境変数

# Override defaults
export LLM_PROVIDER=ollama              # Default provider (already the default)
export LLM_MODEL=gpt-oss                # Default model (already the default)

# For cloud providers (optional)
export OPENAI_API_KEY=sk-...           # For GPT-5, GPT-4, O3 models
export ANTHROPIC_API_KEY=sk-ant-...    # For Claude 4.5, Claude 3.5
export AZURE_OPENAI_API_KEY=sk-...     # For enterprise GPT-5
export AZURE_OPENAI_ENDPOINT=https://...
export GEMINI_API_KEY=...              # For Gemini models
export GROQ_API_KEY=...                # For Groq fast inference

# Tool configuration
export MCP_TOOL_TIMEOUT=120            # Tool execution timeout (seconds)

🌐 利用可能なモード

1. チャットモード（デフォルト）

ストリーミング応答と自動ツール使用に対応した、自然言語インターフェースを提供します。

# Default mode with Ollama/gpt-oss reasoning model (no API key needed)
mcp-cli --server sqlite

# See the AI's thinking process with reasoning models
mcp-cli --server sqlite --model gpt-oss     # Open-source reasoning
mcp-cli --server sqlite --provider openai --model gpt-5  # GPT-5 reasoning
mcp-cli --server sqlite --provider anthropic --model claude-4-5-opus  # Claude 4.5 reasoning

# Use different local models
mcp-cli --server sqlite --model llama3.3
mcp-cli --server sqlite --model qwen2.5-coder

# Switch to cloud providers (requires API keys)
mcp-cli chat --server sqlite --provider openai --model gpt-5
mcp-cli chat --server sqlite --provider anthropic --model claude-4-5-sonnet

# Launch with real-time browser dashboard
mcp-cli --server sqlite --dashboard

# Attach files to the first message
mcp-cli --server sqlite --attach image.png --attach data.csv

2. インタラクティブモード

サーバーを直接操作するための、コマンド駆動型シェルインターフェースです。

mcp-cli interactive --server sqlite

# With specific models
mcp-cli interactive --server sqlite --model gpt-oss       # Local reasoning
mcp-cli interactive --server sqlite --provider openai --model gpt-5  # Cloud GPT-5

3. コマンドモード

自動化やスクリプト作成に適した、Unix 対応インターフェースです。

# Process text with reasoning models
mcp-cli cmd --server sqlite --model gpt-oss --prompt "Think through this step by step" --input data.txt

# Use GPT-5 for complex reasoning
mcp-cli cmd --server sqlite --provider openai --model gpt-5 --prompt "Analyze this data" --input data.txt

# Execute tools directly
mcp-cli cmd --server sqlite --tool list_tables --output tables.json

# Pipeline-friendly processing
echo "SELECT * FROM users LIMIT 5" | mcp-cli cmd --server sqlite --tool read_query --input -

4. 直接コマンド

インタラクティブモードに入らずに、個々のコマンドを実行します。

# List available tools
mcp-cli tools --server sqlite

# Show provider configuration
mcp-cli provider list

# Show available models for current provider
mcp-cli models

# Show models for specific provider
mcp-cli models openai    # Shows GPT-5, GPT-4, O3 models
mcp-cli models anthropic # Shows Claude 4.5, Claude 3.5 models
mcp-cli models ollama    # Shows gpt-oss, llama3.3, etc.

# Ping servers
mcp-cli ping --server sqlite

# List resources
mcp-cli resources --server sqlite

# UI Theme Management
mcp-cli theme                     # Show current theme and list available
mcp-cli theme dark                # Switch to dark theme
mcp-cli theme --select            # Interactive theme selector
mcp-cli theme --list              # List all available themes

# Token Storage Management
mcp-cli token backends            # Show available storage backends
mcp-cli --token-backend encrypted token list  # Use specific backend

🌐 MCP Apps（インタラクティブなブラウザー UI）

MCP Apps を使用すると、ツールサーバーがブラウザーで表示されるインタラクティブな HTML UI を提供できます。ツールに UI リソースを指す _meta.ui アノテーションがある場合、mcp-cli はローカル Web サーバーを自動的に起動し、ブラウザーでアプリを開きます。

前提条件

# Install the apps extra (adds websockets dependency)
pip install "mcp-cli[apps]"

動作の仕組み

アプリ対応ツールを提供する MCP サーバーに接続します
_meta.ui メタデータを持つツール（例：show_chart、show_table）を呼び出します
mcp-cli が UI リソースを自動的に取得し、ローカルサーバーを起動して、ブラウザーを開きます
アプリは WebSocket 経由でツールの結果をリアルタイムに受け取ります

例

# Connect to a server with app-enabled tools
mcp-cli --server view_demo

# In chat, ask for something visual:
> Show me the sales data as a chart
# Browser opens automatically with an interactive chart

# The /tools command shows which tools have app UIs (APP column)
> /tools

アーキテクチャ

ホストページ：アプリの HTML を含むサンドボックス化された iframe を提供します
WebSocket ブリッジ：ブラウザーと MCP サーバー間の JSON-RPC を中継します
セキュリティ：iframe サンドボックス、CSP 保護、XSS 防止、URL スキームの検証
信頼性：切断中のメッセージキューイング、指数バックオフによる再接続、ツール結果の遅延配信

詳しいガイドについては、MCP Apps ドキュメントを参照してください。

🤖 チャットモードの使用

チャットモードは、ストリーミング応答とインテリジェントなツール使用に対応した、最も高度なインターフェースです。

チャットモードの開始

# Simple startup with default reasoning model (gpt-oss)
mcp-cli --server sqlite

# Multiple servers
mcp-cli --server sqlite,filesystem

# With advanced reasoning models
mcp-cli --server sqlite --provider openai --model gpt-5
mcp-cli --server sqlite --provider anthropic --model claude-4-5-opus

チャットコマンド（スラッシュコマンド）

プロバイダーとモデルの管理

/provider                           # Show current configuration (default: ollama)
/provider list                      # List all providers
/provider config                    # Show detailed configuration
/provider diagnostic               # Test provider connectivity
/provider set ollama api_base http://localhost:11434  # Configure Ollama endpoint
/provider openai                   # Switch to OpenAI (requires API key)
/provider anthropic                # Switch to Anthropic (requires API key)
/provider openai gpt-5             # Switch to OpenAI GPT-5

# Custom Provider Management
/provider custom                   # List custom providers
/provider add localai http://localhost:8080/v1 gpt-4  # Add custom provider
/provider remove localai           # Remove custom provider

/model                             # Show current model (default: gpt-oss)
/model llama3.3                    # Switch to different Ollama model
/model gpt-5                       # Switch to GPT-5 (if using OpenAI)
/model claude-4-5-opus             # Switch to Claude 4.5 (if using Anthropic)
/models                            # List available models for current provider

ツールの管理

/tools                             # List available tools
/tools --all                       # Show detailed tool information
/tools --raw                       # Show raw JSON definitions
/tools call                        # Interactive tool execution

/toolhistory                       # Show tool execution history
/th -n 5                          # Last 5 tool calls
/th 3                             # Details for call #3
/th --json                        # Full history as JSON

サーバーの管理（実行時設定）

/server                            # List all configured servers
/server list                       # List servers (alias)
/server list all                   # Include disabled servers

# Add servers at runtime (persists in ~/.mcp-cli/preferences.json)
/server add <name> stdio <command> [args...]
/server add sqlite stdio uvx mcp-server-sqlite --db-path test.db
/server add playwright stdio npx @playwright/mcp@latest
/server add time stdio uvx mcp-server-time
/server add fs stdio npx @modelcontextprotocol/server-filesystem /path/to/dir

# HTTP/SSE server examples with authentication
/server add github --transport http --header "Authorization: Bearer ghp_token" -- https://api.github.com/mcp
/server add myapi --transport http --env API_KEY=secret -- https://api.example.com/mcp
/server add events --transport sse -- https://events.example.com/sse

# Manage server state
/server enable <name>              # Enable a disabled server
/server disable <name>             # Disable without removing
/server remove <name>              # Remove user-added server
/server ping <name>                # Test server connectivity

# Server details
/server <name>                     # Show server configuration details

注：/server add で追加したサーバーは ~/.mcp-cli/preferences.json に保存され、セッションをまたいで保持されます。プロジェクトのサーバーは引き続き server_config.json に保存されます。

マルチモーダル添付ファイル

/attach image.png                  # Stage an image for the next message
/attach code.py                    # Stage a text file
/attach list                       # Show currently staged files
/attach clear                      # Clear staged files
/file data.csv                     # Alias for /attach
/image screenshot.heic             # Alias for /attach

# Inline file references (in any message)
@file:screenshot.png describe what you see
@file:data.csv summarize this data

# Image URLs are auto-detected
https://example.com/photo.jpg what is in this image?

会話の管理

/conversation                      # Show conversation history
/ch -n 10                         # Last 10 messages
/ch 5                             # Details for message #5
/ch --json                        # Full history as JSON

/save conversation.json            # Save conversation to file
/compact                          # Summarize conversation
/clear                            # Clear conversation history
/cls                              # Clear screen only

UI のカスタマイズ

/theme                            # Interactive theme selector with preview
/theme dark                       # Switch to dark theme
/theme monokai                    # Switch to monokai theme

# Available themes: default, dark, light, minimal, terminal, monokai, dracula, solarized
# Themes are persisted across sessions

トークンの管理

/token                            # List all stored tokens
/token list                       # List all tokens explicitly
/token set <name>                 # Store a bearer token
/token get <name>                 # Get token details
/token delete <name>              # Delete a token
/token clear                      # Clear all tokens (with confirmation)
/token backends                   # Show available storage backends

# Examples
/token set my-api                 # Prompts for token value (secure)
/token get notion --oauth         # Get OAuth token for Notion server
/token list --api-keys            # List only provider API keys

トークンの保存バックエンド： MCP CLI は、複数の安全なトークン保存バックエンドに対応しています。

Keychain（macOS）- macOS Keychain を使用します（macOS のデフォルト）
Windows Credential Manager - Windows のネイティブストレージです（Windows のデフォルト）
Secret Service - Linux デスクトップのキーリングです（GNOME/KDE）
暗号化ファイル - AES-256 で暗号化されたローカルファイルです（クロスプラットフォームのフォールバック）
HashiCorp Vault - エンタープライズ向けのシークレット管理です

--token-backend でデフォルトのバックエンドを上書きできます。

# Use encrypted file storage instead of keychain
mcp-cli --token-backend encrypted token list

# Use vault for enterprise environments
mcp-cli --token-backend vault token list

詳しいドキュメントについては、トークン管理ガイドを参照してください。

セッション制御

/verbose                          # Toggle verbose/compact display (Default: Enabled)
/confirm                          # Toggle tool call confirmation (Default: Enabled)
/interrupt                        # Stop running operations
/server                           # Manage MCP servers (see Server Management above)
/help                            # Show all commands
/help tools                       # Help for specific command
/exit                            # Exit chat mode

コマンドの完全なドキュメントについては、コマンドシステムガイドを参照してください。

チャット機能

推論の可視化に対応したストリーミング応答

🧠 推論モデル：gpt-oss、GPT-5、Claude 4 で AI の思考プロセスを確認できます
リアルタイム生成：テキストがトークン単位で表示される様子を確認できます
パフォーマンス指標：単語数/秒、応答時間
スムーズな中断：Ctrl+C でストリーミングを停止できます
段階的なレンダリング：ストリーミング中に Markdown 形式で表示します

ツールの実行

ツールを自動的に検出して使用
進行状況インジケーター付きの並行実行
詳細表示モードとコンパクト表示モード
実行履歴と所要時間の完全な記録

マルチモーダル添付ファイル

画像、テキストファイル、音声を任意のメッセージに添付
ステージング、一覧表示、クリアに対応した /attach コマンド（エイリアス：/file、/image）
任意のメッセージ内でのインライン @file:path 参照
最初のメッセージに添付するための --attach CLI フラグ
ドラッグ＆ドロップとクリップボードからの貼り付けに対応したブラウザーの「+」ボタン（--dashboard を使用）
ダッシュボードでサムネイル、テキストプレビュー、音声プレーヤーを表示

プロバイダー連携

プロバイダー間をシームレスに切り替え
モデルに応じた最適化
API キーとエンドポイントの管理
ヘルスモニタリングと診断

🖥️ インタラクティブモードの使用

インタラクティブモードでは、サーバーと直接やり取りするためのコマンドシェルを利用できます。

インタラクティブモードの開始

mcp-cli interactive --server sqlite

インタラクティブコマンド

help                              # Show available commands
exit                              # Exit interactive mode
clear                             # Clear terminal

# Provider management
provider                          # Show current provider
provider list                     # List providers
provider anthropic                # Switch provider
provider openai gpt-5             # Switch to GPT-5

# Model management
model                             # Show current model
model gpt-oss                     # Switch to reasoning model
model claude-4-5-opus             # Switch to Claude 4.5
models                            # List available models

# Tool operations
tools                             # List tools
tools --all                       # Detailed tool info
tools call                        # Interactive tool execution

# Server operations
servers                           # List servers
ping                              # Ping all servers
resources                         # List resources
prompts                           # List prompts

📄 コマンドモードの使用

コマンドモードでは、Unix との親和性が高い自動化機能を利用できます。

コマンドモードのオプション

--input FILE                      # Input file (- for stdin)
--output FILE                     # Output file (- for stdout)
--prompt TEXT                     # Prompt template
--tool TOOL                       # Execute specific tool
--tool-args JSON                  # Tool arguments as JSON
--system-prompt TEXT              # Custom system prompt
--raw                             # Raw output without formatting
--single-turn                     # Disable multi-turn conversation
--max-turns N                     # Maximum conversation turns

例

# Text processing with reasoning models
echo "Analyze this data" | mcp-cli cmd --server sqlite --model gpt-oss --input - --output analysis.txt

# Use GPT-5 for complex analysis
mcp-cli cmd --server sqlite --provider openai --model gpt-5 --prompt "Provide strategic analysis" --input report.txt

# Tool execution
mcp-cli cmd --server sqlite --tool list_tables --raw

# Complex queries
mcp-cli cmd --server sqlite --tool read_query --tool-args '{"query": "SELECT COUNT(*) FROM users"}'

# Batch processing with GNU Parallel
ls *.txt | parallel mcp-cli cmd --server sqlite --input {} --output {}.summary --prompt "Summarize: {{input}}"

🔧 プロバイダーの設定

Ollama の設定（デフォルト）

Ollama はデフォルトで http://localhost:11434 上でローカル実行されます。MCP CLI v0.11.1+ と CHUK-LLM v0.16+ には llama.cpp 統合が含まれており、Ollama でダウンロード済みのモデルを自動検出して再利用するため、再ダウンロードせずに推論を 1.53 倍高速化できます（毎秒 204 トークンから 311 トークン）。

推論モデルやその他のモデルを使用するには、次のようにします。

# Pull reasoning and other models for Ollama
ollama pull gpt-oss          # Default reasoning model
ollama pull llama3.3         # Latest Llama
ollama pull llama3.2         # Llama 3.2
ollama pull qwen3            # Qwen 3
ollama pull qwen2.5-coder    # Coding-focused
ollama pull deepseek-coder   # DeepSeek coder
ollama pull granite3.3       # IBM Granite
ollama pull mistral          # Mistral
ollama pull gemma3           # Google Gemma
ollama pull phi3             # Microsoft Phi
ollama pull codellama        # Code Llama

# List available Ollama models
ollama list

# Configure remote Ollama server
mcp-cli provider set ollama api_base http://remote-server:11434

クラウドプロバイダーの設定

高度なモデルをクラウドプロバイダーで使用するには、API キーを設定します。

# Configure OpenAI (for GPT-5, GPT-4, O3 models)
mcp-cli provider set openai api_key sk-your-key-here

# Configure Anthropic (for Claude 4.5, Claude 3.5)
mcp-cli provider set anthropic api_key sk-ant-your-key-here

# Configure Azure OpenAI (for enterprise GPT-5)
mcp-cli provider set azure_openai api_key sk-your-key-here
mcp-cli provider set azure_openai api_base https://your-resource.openai.azure.com

# Configure other providers
mcp-cli provider set gemini api_key your-gemini-key
mcp-cli provider set groq api_key your-groq-key

# Test configuration
mcp-cli provider diagnostic openai
mcp-cli provider diagnostic anthropic

カスタムの OpenAI 互換プロバイダー

MCP CLI は、カスタムの OpenAI 互換プロバイダー（LocalAI、カスタムプロキシなど）の追加をサポートしています。

# Add a custom provider (persisted across sessions)
mcp-cli provider add localai http://localhost:8080/v1 gpt-4 gpt-3.5-turbo
mcp-cli provider add myproxy https://proxy.example.com/v1 custom-model-1 custom-model-2

# Set API key via environment variable (never stored in config)
export LOCALAI_API_KEY=your-api-key
export MYPROXY_API_KEY=your-api-key

# List custom providers
mcp-cli provider custom

# Use custom provider
mcp-cli --provider localai --server sqlite
mcp-cli --provider myproxy --model custom-model-1 --server sqlite

# Remove custom provider
mcp-cli provider remove localai

# Runtime provider (session-only, not persisted)
mcp-cli --provider temp-ai --api-base https://api.temp.com/v1 --api-key test-key --server sqlite

セキュリティに関する注意：API キーは、OS ネイティブのキーチェーン（macOS Keychain、Windows Credential Manager、Linux Secret Service）または HashiCorp Vault を使って、トークン管理システムに安全に保存できます。または、{PROVIDER_NAME}_API_KEY の形式に従った環境変数を使用するか、--api-key を渡してセッション中のみ使用できます。詳細については、トークン管理を参照してください。

手動設定

~/.chuk_llm/config.yaml にある chuk_llm ライブラリの設定：

ollama:
  api_base: http://localhost:11434
  default_model: gpt-oss

openai:
  api_base: https://api.openai.com/v1
  default_model: gpt-5

anthropic:
  api_base: https://api.anthropic.com
  default_model: claude-4-5-opus

azure_openai:
  api_base: https://your-resource.openai.azure.com
  default_model: gpt-5

gemini:
  api_base: https://generativelanguage.googleapis.com
  default_model: gemini-2.0-flash

groq:
  api_base: https://api.groq.com
  default_model: llama-3.1-70b

API キーは次の方法で指定できます。

安全なトークン保存（推奨） - OS のキーチェーン／Vault に保存します。詳細については、トークン管理を参照してください。
環境変数 - シェルでエクスポートするか、~/.chuk_llm/.env に追加します。

OPENAI_API_KEY=sk-your-key-here
ANTHROPIC_API_KEY=sk-ant-your-key-here
AZURE_OPENAI_API_KEY=sk-your-azure-key-here
GEMINI_API_KEY=your-gemini-key
GROQ_API_KEY=your-groq-key

コマンドライン - --api-key を渡してセッション中のみ使用します（保存されません）。

📂 サーバー設定

MCP CLI は、次の 2 種類のサーバー設定をサポートしています。

プロジェクトサーバー（server_config.json）：プロジェクトレベルで共有する設定
ユーザーサーバー（~/.mcp-cli/preferences.json）：実行時に追加され、セッションをまたいで保持される個人用サーバー

設定ファイルの検索

MCP CLI は、次の優先順位で server_config.json を検索します。

明示的なパス：--config-file オプションで指定します。
```
mcp-cli --config-file /path/to/custom-config.json
```
カレントディレクトリ：プロジェクトディレクトリから実行すると、自動的に検出されます。
```
cd /path/to/my-project
mcp-cli --server sqlite    # Uses ./server_config.json if it exists
```
同梱のデフォルト設定：uvx 経由で実行する場合、またはローカル設定がないディレクトリから実行する場合に使用されます。
```
uvx mcp-cli --server cloudflare_workers    # Uses packaged server_config.json
```

これにより、次のことができます。

プロジェクトごとに上書き：プロジェクト固有のサーバー設定を含む server_config.json をプロジェクトディレクトリに配置します。
デフォルトをグローバルに使用：どこからでも uvx mcp-cli を実行すると、同梱のデフォルトサーバーを利用できます。
明示的にカスタマイズ：--config-file を使用して、任意の設定ファイルの場所を指定します。

同梱のデフォルトサーバー

MCP CLI v0.11.1+ には、同梱の server_config.json に、事前設定済みサーバーが追加されています。

サーバー	タイプ	説明	設定
sqlite	STDIO	SQLite データベース操作	`uvx mcp-server-sqlite --db-path test.db`
echo	STDIO	テスト用エコーサーバー	`uvx chuk-mcp-echo stdio`
math	STDIO	数学的計算	`uvx chuk-mcp-math-server`
playwright	STDIO	ブラウザーの自動化	`npx @playwright/mcp@latest`
brave_search	STDIO	Brave API によるウェブ検索	`BRAVE_API_KEY` トークンが必要です
notion	HTTP	Notion ワークスペースとの連携	`https://mcp.notion.com/mcp`（OAuth）
cloudflare_workers	HTTP	Cloudflare Workers バインディング	`https://bindings.mcp.cloudflare.com/mcp`（OAuth）
monday	HTTP	Monday.com との連携	`https://mcp.monday.com/mcp`（OAuth）
linkedin	HTTP	LinkedIn との連携	`https://linkedin.chukai.io/mcp`
weather	HTTP	天気データサービス	`https://weather.chukai.io/mcp`

注：HTTP サーバーと API ベースのサーバーでは認証が必要です。アクセストークンの設定には、トークン管理システムを使用してください。

これらのサーバーを使用するには：

# Use bundled servers from anywhere
uvx mcp-cli --server sqlite
uvx mcp-cli --server echo
uvx mcp-cli --server math
uvx mcp-cli --server playwright

# API-based servers require tokens
mcp-cli token set brave_search --type bearer
uvx mcp-cli --server brave_search

# HTTP/OAuth servers require OAuth authentication
uvx mcp-cli token set notion --oauth
uvx mcp-cli --server notion

# Use multiple servers simultaneously
uvx mcp-cli --server sqlite,math,playwright

プロジェクトの設定

MCP サーバーの設定を記述した server_config.json ファイルを作成します。

{
  "mcpServers": {
    "sqlite": {
      "command": "python",
      "args": ["-m", "mcp_server.sqlite_server"],
      "env": {
        "DATABASE_PATH": "database.db"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"],
      "env": {}
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": {
        "BRAVE_API_KEY": "${TOKEN:bearer:brave_search}"
      }
    },
    "notion": {
      "url": "https://mcp.notion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TOKEN:bearer:notion}"
      }
    }
  }
}

トークンの安全な置換

MCP CLI は、${TOKEN:namespace:name} 構文を使用して、安全なストレージからトークンを自動的に置換できます。

構文：${TOKEN:<namespace>:<token-name>}

例：

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": {
        "BRAVE_API_KEY": "${TOKEN:bearer:brave_search}"
      }
    },
    "api-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TOKEN:bearer:my_api}",
        "X-API-Key": "${TOKEN:api-key:my_service}"
      }
    }
  }
}

トークンの保存先：

# Store tokens securely (never in config files!)
mcp-cli token set brave_search --type bearer
# Enter token value when prompted (hidden input)

mcp-cli token set my_api --type bearer --value "your-token-here"

# Tokens are stored in OS-native secure storage:
# - macOS: Keychain
# - Windows: Credential Manager
# - Linux: Secret Service (GNOME Keyring/KWallet)

対応する場所：

env：STDIO サーバー用の環境変数
headers：HTTP/SSE サーバー用の HTTP ヘッダー

名前空間：

bearer：Bearer トークン（--type bearer のデフォルト）
api-key：API キー（--type api-key のデフォルト）
oauth：OAuth トークン（自動）
generic：カスタムトークン

メリット：

✅ API キーを設定ファイルに保存する必要はありません
✅ server_config.json を安全に共有できます（シークレットは含まれません）
✅ トークンは OS ネイティブの安全なストレージで暗号化されます
✅ すべてのトランスポートタイプ（STDIO、HTTP、SSE）で動作します

詳しくは、トークン管理ガイドをご覧ください。

実行時のサーバー管理

設定ファイルを編集せずに、実行時にサーバーを動的に追加できます。

# Add STDIO servers (most common)
mcp-cli
> /server add sqlite stdio uvx mcp-server-sqlite --db-path mydata.db
> /server add playwright stdio npx @playwright/mcp@latest
> /server add time stdio uvx mcp-server-time

# Add HTTP servers with authentication
> /server add github --transport http --header "Authorization: Bearer ghp_token" -- https://api.github.com/mcp
> /server add myapi --transport http --env API_KEY=secret -- https://api.example.com/mcp

# Add SSE (Server-Sent Events) servers
> /server add events --transport sse -- https://events.example.com/sse

# Manage servers
> /server list                     # Show all servers
> /server disable sqlite           # Temporarily disable
> /server enable sqlite            # Re-enable
> /server remove myapi             # Remove user-added server

主なポイント：

ユーザーが追加したサーバーは ~/.mcp-cli/preferences.json に保存されます
アプリケーションを再起動しても保持されます
削除せずに有効化／無効化できます
STDIO、HTTP、SSE トランスポートに対応しています
認証用の環境変数とヘッダーを設定できます

📈 高度な使用例

推論モデルの比較

# Compare reasoning across different models
> /provider ollama
> /model gpt-oss
> Think through this problem step by step: If a train leaves New York at 3 PM...
[See the complete thinking process with gpt-oss]

> /provider openai
> /model gpt-5
> Think through this problem step by step: If a train leaves New York at 3 PM...
[See GPT-5's reasoning approach]

> /provider anthropic
> /model claude-4-5-opus
> Think through this problem step by step: If a train leaves New York at 3 PM...
[See Claude 4.5's analytical process]

推論を活用したローカルファーストのワークフロー

# Start with default Ollama/gpt-oss (no API key needed)
mcp-cli chat --server sqlite

# Use reasoning model for complex problems
> Think through this database optimization problem step by step
[gpt-oss shows its complete thinking process before answering]

# Try different local models for different tasks
> /model llama3.3              # General purpose
> /model qwen2.5-coder         # For coding tasks
> /model deepseek-coder        # Alternative coding model
> /model granite3.3            # IBM's model
> /model gpt-oss               # Back to reasoning model

# Switch to cloud when needed (requires API keys)
> /provider openai
> /model gpt-5
> Complex enterprise architecture design...

> /provider anthropic
> /model claude-4-5-opus
> Detailed strategic analysis...

> /provider ollama
> /model gpt-oss
> Continue with local processing...

マルチプロバイダーのワークフロー

# Start with local reasoning (default, no API key)
mcp-cli chat --server sqlite

# Compare responses across providers
> /provider ollama
> What's the best way to optimize this SQL query?

> /provider openai gpt-5        # Requires API key
> What's the best way to optimize this SQL query?

> /provider anthropic claude-4-5-sonnet  # Requires API key
> What's the best way to optimize this SQL query?

# Use each provider's strengths
> /provider ollama gpt-oss      # Local reasoning, privacy
> /provider openai gpt-5        # Advanced reasoning
> /provider anthropic claude-4-5-opus  # Deep analysis
> /provider groq llama-3.1-70b  # Ultra-fast responses

推論を活用した複雑なツールのワークフロー

# Use reasoning model for complex database tasks
> /model gpt-oss
> I need to analyze our database performance. Think through what we should check first.
[gpt-oss shows thinking: "First, I should check the table structure, then indexes, then query patterns..."]
[Tool: list_tables] → products, customers, orders

> Now analyze the indexes and suggest optimizations
[gpt-oss thinks through index analysis]
[Tool: describe_table] → Shows current indexes
[Tool: read_query] → Analyzes query patterns

> Create an optimization plan based on your analysis
[Complete reasoning process followed by specific recommendations]

自動化とスクリプト

# Batch processing with different models
for file in data/*.csv; do
  # Use reasoning model for analysis
  mcp-cli cmd --server sqlite \
    --model gpt-oss \
    --prompt "Analyze this data and think through patterns" \
    --input "$file" \
    --output "analysis/$(basename "$file" .csv)_reasoning.txt"
  
  # Use coding model for generating scripts
  mcp-cli cmd --server sqlite \
    --model qwen2.5-coder \
    --prompt "Generate Python code to process this data" \
    --input "$file" \
    --output "scripts/$(basename "$file" .csv)_script.py"
done

# Pipeline with reasoning
cat complex_problem.txt | \
  mcp-cli cmd --model gpt-oss --prompt "Think through this step by step" --input - | \
  mcp-cli cmd --model llama3.3 --prompt "Summarize the key points" --input - > solution.txt

パフォーマンスのモニタリング

# Check provider and model performance
> /provider diagnostic
Provider Diagnostics
Provider      | Status      | Response Time | Features      | Models
ollama        | ✅ Ready    | 56ms         | 📡🔧         | gpt-oss, llama3.3, qwen3, ...
openai        | ✅ Ready    | 234ms        | 📡🔧👁️      | gpt-5, gpt-4o, o3, ...
anthropic     | ✅ Ready    | 187ms        | 📡🔧         | claude-4-5-opus, claude-4-5-sonnet, ...
azure_openai  | ✅ Ready    | 198ms        | 📡🔧👁️      | gpt-5, gpt-4o, ...
gemini        | ✅ Ready    | 156ms        | 📡🔧👁️      | gemini-2.0-flash, ...
groq          | ✅ Ready    | 45ms         | 📡🔧         | llama-3.1-70b, ...

# Check available models
> /models
Models for ollama (Current Provider)
Model                | Status
gpt-oss             | Current & Default (Reasoning)
llama3.3            | Available
llama3.2            | Available
qwen2.5-coder       | Available
deepseek-coder      | Available
granite3.3          | Available
... and 6 more

# Monitor tool execution with reasoning
> /verbose
> /model gpt-oss
> Analyze the database and optimize the slowest queries
[Shows complete thinking process]
[Tool execution with timing]

🔍 トラブルシューティング

よくある問題

Ollama が起動していない（デフォルトのプロバイダー）：

# Start Ollama service
ollama serve

# Or check if it's running
curl http://localhost:11434/api/tags

モデルが見つからない：

# For Ollama (default), pull the model first
ollama pull gpt-oss      # Reasoning model
ollama pull llama3.3     # Latest Llama
ollama pull qwen2.5-coder # Coding model

# List available models
ollama list

# For cloud providers, check supported models
mcp-cli models openai     # Shows GPT-5, GPT-4, O3 models
mcp-cli models anthropic  # Shows Claude 4.5, Claude 3.5 models

プロバイダーが見つからない、または API キーがない：

# Check available providers
mcp-cli provider list

# For cloud providers, set API keys
mcp-cli provider set openai api_key sk-your-key
mcp-cli provider set anthropic api_key sk-ant-your-key

# Test connection
mcp-cli provider diagnostic openai

Ollama との接続に関する問題：

# Check Ollama is running
ollama list

# Test connection
mcp-cli provider diagnostic ollama

# Configure custom endpoint if needed
mcp-cli provider set ollama api_base http://localhost:11434

デバッグモード

トラブルシューティングのため、詳細ログを有効にします。

mcp-cli --verbose chat --server sqlite
mcp-cli --log-level DEBUG interactive --server sqlite

# Write debug logs to a rotating file (secrets are automatically redacted)
mcp-cli --log-file ~/.mcp-cli/logs/debug.log --server sqlite

🔒 セキュリティに関する考慮事項

プライバシーとローカルファースト

デフォルトでローカル：gpt-oss を使用する Ollama はローカルで動作するため、データのプライバシーが保たれます
クラウド不要：外部 API に依存せず、すべての機能を利用できます

トークンと認証のセキュリティ

セキュアなトークン保存：トークンは OS ネイティブの認証情報ストア（macOS Keychain、Windows Credential Manager、Linux Secret Service）に、「mcp-cli」サービス識別子のもとで保存されます。
複数の保存バックエンド：セキュリティ要件に応じて、キーチェーン、暗号化ファイル、HashiCorp Vault から選択できます。
API キー：クラウドプロバイダー（OpenAI、Anthropic など）でのみ必要となり、トークン管理システムを使って安全に保存されます。
OAuth 2.0 サポート：PKCE とリソースインジケーター（RFC 7636、RFC 8707）を使って、MCP サーバーを安全に認証します。

ログのセキュリティ

シークレットのマスキング：すべてのログ出力（コンソールとファイル）で、Bearer トークン、API キー（sk-*）、OAuth アクセストークン、Authorization ヘッダーが自動的にマスキングされます。
ローテーションするファイルログ：オプションの --log-file では、JSON 形式、10MB のローテーション、3 つのバックアップファイルを利用できます。

実行のセキュリティ

ツールの検証：すべてのツール呼び出しは実行前に検証されます。
タイムアウト保護：設定可能なタイムアウトにより、処理がハングするのを防ぎます（v0.13+）。
サーキットブレーカー：連鎖的な障害を防ぐため、障害を自動的に検出して復旧します（v0.13+）。
サーバーの分離：各サーバーは独自のプロセスで実行されます。
ファイルアクセス：--disable-filesystem でファイルシステムへのアクセスを無効にできます。
トランスポートの監視：接続障害を自動的に検出し、警告を表示します（v0.11+）。

MCP Apps のセキュリティ

iframe サンドボックス：アプリは権限を制限したサンドボックス化 iframe 内で実行されます。
コンテンツセキュリティポリシー：サーバーから提供された CSP ドメインは検証され、サニタイズされます。
XSS の防止：ツール名とユーザー提供のコンテンツは、テンプレートに挿入する前に HTML エスケープされます。
URL スキームの検証：ui/open-link で許可されるのは http:// と https:// のスキームのみです。
ツール名の検証：ブリッジは、MCP 仕様で定められた文字セットに一致しないツール名を拒否します。
WebSocket オリジンの検証（v0.20.1+）：ローカルの app-host サーバーは、Origin ヘッダーが自身の http://localhost:<port> ホストページと一致しない WebSocket ハンドシェイクを拒否します。これにより、無関係なウェブページが実行中のアプリのブリッジに接続できないようにします。
ツール権限の適用（v0.20.1+）：リソースが呼び出し可能なツールの許可リストを宣言している場合、ブリッジはツール名の構文チェックだけでなく、すべての tools/call でそのリストを適用します。
SSRF 対策済みのリソース取得（v0.20.1+）：直接の HTTP(S) リソース取得では、接続前にプライベート／ループバック／リンクローカルのアドレス範囲との照合を行い、リダイレクトのたびに再検証します。

ダッシュボードのセキュリティ（v0.20.1+）

WebSocket オリジンの検証：ダッシュボードの WebSocket サーバーは、MCP Apps と同じオリジンチェックを実施します。
サニタイズされた Markdown のレンダリング：アシスタントのチャットメッセージは、独自実装のサニタイザーではなく DOMPurify を通してレンダリングされます。
エスケープされたビューのメタデータ：サーバーが宣言するビュー名とアイコンは、パネルのヘッダーに挿入する前に HTML エスケープされます。
サニタイズされたエージェント／セッションのパス：エージェントとセッションの識別子は、ファイルシステムのパス構成要素として使用する前にサニタイズされます。

プラン実行のセキュリティ（v0.20.1+）

ツールの確認を徹底：プランの実行（/plan、plan_create_and_execute）では、対話型チャットと同じツール確認の設定と信頼済みドメインのポリシーが適用されます。確認が必要で、確認プロンプトを表示できない場合は、未確認のまま実行せず、呼び出しを拒否します。

🚀 パフォーマンス機能

LLM プロバイダーのパフォーマンス（v0.16+）

インポートが 52 倍高速：遅延読み込みにより、735ms から 14ms に短縮しました。
クライアント作成が 112 倍高速：スレッドセーフなキャッシュを自動的に利用します。
llama.cpp との統合：Ollama モデルを自動的に再利用することで、推論速度が 1.53 倍（毎秒 204 トークンから 311 トークン）になります。
動的なモデル検出：機能に基づくモデル選択をオーバーヘッドなしで行えます。

ツール実行パフォーマンス（v0.13+）

本番環境向けミドルウェア：タイムアウト、指数バックオフによる再試行、サーキットブレーカー、結果のキャッシュ
並行ツール実行：適切に連携しながら、複数のツールを同時に実行できます
接続状態の監視：トランスポート障害を自動的に検出し、復旧します
最適化されたツールマネージャー：すべての機能を維持しながら、コードを2000行以上から約800行に削減

ランタイムパフォーマンス

ローカル処理：デフォルトのOllamaプロバイダーにより、レイテンシを最小限に抑えます
推論の可視化：gpt-oss、GPT-5、Claude 4の思考プロセスを確認できます
ストリーミング応答：応答をリアルタイムで生成します
コネクションプーリング：クライアント接続を効率的に再利用します
キャッシュ：ツールのメタデータとプロバイダー設定をキャッシュします
非同期アーキテクチャ：全体を通してノンブロッキング処理を行います

📦 依存関係

コア依存関係は、機能グループごとに整理されています。

cli：ターミナルUIとコマンドフレームワーク（Rich、Typer、chuk-term）
dev：開発ツール、テストユーティリティ、リンティング
chuk-tool-processor v0.22+：ミドルウェア、複数の実行戦略、可観測性を備えた、本番環境向けのツール実行
chuk-llm v0.17+：動的なモデル検出、機能ベースの選択、llama.cpp統合を備えた統合LLMプロバイダー
chuk-term：テーマ、プロンプト、クロスプラットフォーム対応を備えた強化版ターミナルUI

特定の機能を指定してインストールします。

pip install "mcp-cli[cli]"        # Basic CLI features
pip install "mcp-cli[cli,dev]"    # CLI with development tools
pip install "mcp-cli[apps]"       # MCP Apps (interactive browser UIs)

🤝 コントリビューション

コントリビューションを歓迎します。詳細については、コントリビューションガイドをご覧ください。

開発環境のセットアップ

git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli
pip install -e ".[cli,dev]"
pre-commit install

デモスクリプト

MCP CLIの機能を確認できます。

# Command Mode Demos

# General cmd mode features (bash)
bash examples/cmd_mode_demo.sh

# LLM integration with cmd mode (bash)
bash examples/cmd_mode_llm_demo.sh

# Python integration example
uv run examples/cmd_mode_python_demo.py

# Custom Provider Management Demos

# Interactive walkthrough demo (educational)
uv run examples/custom_provider_demo.py

# Working demo with actual inference (requires OPENAI_API_KEY)
uv run examples/custom_provider_working_demo.py

# Simple shell script demo (requires OPENAI_API_KEY)
bash examples/custom_provider_simple_demo.sh

# Terminal management features (chuk-term)
uv run examples/ui_terminal_demo.py

# Output system with themes (chuk-term)
uv run examples/ui_output_demo.py

# Streaming UI capabilities (chuk-term)
uv run examples/ui_streaming_demo.py

テストの実行

pytest
pytest --cov=mcp_cli --cov-report=html

📜 ライセンス

このプロジェクトはApache License 2.0の下でライセンスされています。詳細については、LICENSEファイルをご覧ください。

🙏 謝辞

CHUK Tool Processor - ミドルウェアと可観測性を備えた、本番環境向けの非同期ツール実行
CHUK-LLM - 動的なモデル検出、llama.cpp統合、GPT-5／Claude 4.5対応（v0.17+）を備えた統合LLMプロバイダー
CHUK-Term - テーマとクロスプラットフォーム対応を備えた強化版ターミナルUI
Rich - 美しいターミナル表示
Typer - CLIフレームワーク
Prompt Toolkit - 対話型入力

🔗 関連プロジェクト

Model Context Protocol - コアプロトコル仕様
MCP Servers - 公式MCPサーバー実装
CHUK Tool Processor - ミドルウェアと可観測性を備えた、本番環境向けのツール実行
CHUK-LLM - 動的なモデル検出、GPT-5、Claude 4.5、O3シリーズへの対応、llama.cpp統合を備えたLLMプロバイダー抽象化
CHUK-Term - テーマとクロスプラットフォーム対応を備えたターミナルUIライブラリ

Markdown 対応

ログインしてコメント

基本情報

開発元: chrishayuk
カテゴリ: フレームワーク・SDK
GitHub スター: 2,022
ライセンス: View license
ランタイム: python
掲載日: 2025年2月23日
最終更新: 13 週間前

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。