simpletel

simpletel-mcp

simpletel 用の Model Context Protocol サーバーです。コーディングエージェントに 「今、何が起きましたか？」 と尋ねると、稼働中のサービスの OpenTelemetry トレース、ログ、メトリクス、アカウント使用状況を読み取れます。

simpletel mcp は simpletel CLI に組み込まれた stdio MCP サーバーです。標準入力／標準出力で改行区切りの JSON-RPC 2.0 を使用し（MCP プロトコルリビジョンは 2025-06-18）、simpletel の読み取りコマンドをネイティブなエージェントツールとして公開します。単一の静的バイナリのため、ランタイム、依存関係、バックグラウンドサービスは不要です。

• CLI は次の1行でインストールできます：curl -fsSL https://simpletel.dev/install | sh
• simpletel mcp として実行します
• または、コンテナを使用します：ghcr.io/willnewby/simpletel-mcp
• レジストリ名：io.github.willnewby/simpletel

---

ツール

サーバーは4つのツールを公開します。各ツールはテキスト（対応する CLI コマンドが生成する JSON ドキュメント）を返します。ツール側でエラーが発生した場合は、isError: true を含む通常の結果として返されるため、ツール呼び出しによってセッションが中断されることはありません。

ツール	引数	機能
get_traces	since（既定値は 1h）、service、errors_only、min_duration、limit	このチームのトレースを新しい順に一覧表示します。simpletel get traces --format json が生成する JSON ドキュメントです。失敗または低速なリクエストの特定に使用します。
get_trace	trace_id（必須）	1件のトレース全体（スパン、スパンイベント、関連するログレコード）を取得します。simpletel get trace <id> --format json が生成する JSON ドキュメントです。
verify	service（必須）、timeout（既定値は 60s）	オンボーディング確認の simpletel verify を実行します。ライブラリによるインストルメンテーションのスパンを含む新しいトレースが service に届くまでポーリングします。段階レポートと終了ステータス（確認済みは 0、期限切れは 1）を返します。期限切れは確認処理の完了を意味し、ツールエラーではありません。
usage	(なし)	アカウントのプラン、当月のレコード数、許容量、支出上限を表示します。simpletel usage --format json が生成する JSON ドキュメントです。アカウント単位であり、ログイン済みユーザートークンが必要です。

get_traces、get_trace、verify はチーム単位、usage はアカウント単位です。

---

認証とチームの解決

サーバーは起動時に1つの接続先を解決します。優先順位は、ほかのすべての simpletel 読み取りコマンドと同じです：フラグ > 環境変数 > 設定ファイル > 既定値。

設定	フラグ	環境変数	設定ファイル	既定値
エンドポイント	--endpoint	SIMPLETEL_ENDPOINT	endpoint	http://localhost:4318
チーム	--team	SIMPLETEL_TEAM	current_team	(なし)
管理者トークン	--admin-token	SIMPLETEL_ADMIN_TOKEN	—	(なし)
ユーザートークン（usage 用）	—	SIMPLETEL_TOKEN	auth トークン	(なし)
設定ファイルのパス	--config	SIMPLETEL_CONFIG	—	~/.simpletel/config.toml

• 設定ファイルは ~/.simpletel/config.toml です。simpletel login および simpletel team が書き込みます（モード 0600）。simpletel login で GitHub を使ってサインインし、simpletel team create / simpletel team use で現在のチームを設定します。
• --team には20桁の16進数のチーム ID（そのまま使用され、トークンは不要）またはわかりやすい名前を指定できます。名前は解決のみ行われ、作成されることはありません。名前の検索には管理者トークンが必要です。
• usage にはユーザートークンも必要です。simpletel login を実行するか、SIMPLETEL_TOKEN（stk_… トークン）を設定してください。

チームが指定されていないか、正しくない場合でも、サーバーは initialize と tools/list に応答するため、クライアントはツールカタログを確認できます。その後、チーム単位の各呼び出しは、問題を独自の isError 結果として報告します。

このサーバーから simpletel に送信されるのは、設定したエンドポイントに対してツールが行う読み取りリクエストだけです。診断情報は stderr に出力され、stdout にはプロトコルメッセージのみが出力されます。

---

インストール

1. CLI をインストールする

curl -fsSL https://simpletel.dev/install | sh

simpletel を ~/.simpletel/bin/ にインストールします（sha256 を検証してください。sudo は不要で、確認プロンプトも表示されません）。次に、サインインしてチームを作成または選択します。

simpletel login            # GitHub device flow
simpletel team create --name my-team

2. サーバーをクライアントに登録する

MCP サブコマンドは simpletel mcp です。接続フラグ --endpoint、--team、--admin-token、--config を受け取ります。

Claude Code

# by 20-hex team id (no extra credentials needed)
claude mcp add simpletel -- ~/.simpletel/bin/simpletel mcp --team <20-hex-team-id>

# or rely on the logged-in config file (~/.simpletel/config.toml)
claude mcp add simpletel -- ~/.simpletel/bin/simpletel mcp

代わりに --env を使って、接続値を環境変数として渡すこともできます。

claude mcp add simpletel \
  --env SIMPLETEL_ENDPOINT=https://simpletel.dev \
  --env SIMPLETEL_TEAM=<20-hex-team-id> \
  -- ~/.simpletel/bin/simpletel mcp

Claude Desktop / JSON 設定に対応したクライアント全般（claude_desktop_config.json、 Cursor、Cline、Windsurf、…）：

{
  "mcpServers": {
    "simpletel": {
      "command": "/Users/you/.simpletel/bin/simpletel",
      "args": ["mcp"],
      "env": {
        "SIMPLETEL_ENDPOINT": "https://simpletel.dev",
        "SIMPLETEL_TEAM": "<20-hex-team-id>"
      }
    }
  }
}

ローカルでログイン済みの場合は、env を省略できます。command は ~/.simpletel/config.toml を読み込みます。ホームディレクトリを読み取れない サンドボックス化されたクライアントでは、代わりに env（または --env / --router に相当するオプション）を通じて値を渡してください。

---

Docker

イメージには CLI が含まれており、simpletel mcp を実行します。対応プラットフォームは linux/amd64 と linux/arm64 です。

docker run -i --rm ghcr.io/willnewby/simpletel-mcp:latest

コンテナには認証情報が設定されていません。設定ファイルをマウントするか、環境変数で渡してください（推奨 — イメージには何も書き込まれません）。

既存の設定ファイルを読み取り専用でマウントします。イメージは distroless の nonroot ユーザー（uid/gid 65532）として実行され、HOME=/home/nonroot が設定されているため、コンテナ内での CLI のデフォルト設定ファイルパスは /home/nonroot/.simpletel/config.toml です。simpletel login はファイルのモードを 0600 に設定して書き込むため、読み取り可能な状態を保てるよう、ファイルの所有者としてコンテナを実行してください。

docker run -i --rm \
  --user "$(id -u):$(id -g)" \
  -v "$HOME/.simpletel/config.toml:/home/nonroot/.simpletel/config.toml:ro" \
  ghcr.io/willnewby/simpletel-mcp:latest

（以下の -e で接続情報を渡せば、所有権の問題を完全に回避できるため、この方法を推奨します。）

または、すべての値を環境変数で渡します。

docker run -i --rm \
  -e SIMPLETEL_ENDPOINT=https://simpletel.dev \
  -e SIMPLETEL_TEAM=<20-hex-team-id> \
  ghcr.io/willnewby/simpletel-mcp:latest

JSON クライアントのエントリーとして：

{
  "mcpServers": {
    "simpletel": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SIMPLETEL_ENDPOINT=https://simpletel.dev",
        "-e", "SIMPLETEL_TEAM=<20-hex-team-id>",
        "ghcr.io/willnewby/simpletel-mcp:latest"
      ]
    }
  }
}

MCP トランスポートは stdio なので、-i（標準入力を開いたままにする）が必要です。また、-t は追加しないでください。

---

設定リファレンス

simpletel mcp [--endpoint URL] [--team <id-or-name>] [--admin-token TOKEN] [--config PATH]

変数	用途
SIMPLETEL_ENDPOINT	サーバーのベース URL — /v1/traces のサフィックスは付けません（デフォルトは http://localhost:4318）。
SIMPLETEL_TEAM	20 桁の 16 進数のチーム ID、または分かりやすい名前（名前には管理者トークンが必要です）。
SIMPLETEL_ADMIN_TOKEN	チームの名前を解決するためのトークン。20 桁の 16 進数の ID には不要です。
SIMPLETEL_TOKEN	usage ツールで使用するユーザートークン（stk_…）。
SIMPLETEL_CONFIG	設定ファイルのパス（デフォルトは ~/.simpletel/config.toml）。

---

制限事項

• stdio のみです。 simpletel mcp はクライアントによってサブプロセスとして起動されます。HTTP/SSE エンドポイントではありません。
• 読み取り専用です。 ツールはトレース、使用状況、オンボーディングの状態を照会します。データの取り込みやアカウント設定の変更は行いません。
• コンテナを使わない場合は、ホストの CLI が必要です。simpletel バイナリはビルド時に Dockerfile によって取得されます。このリポジトリにはバイナリ自体は含まれていません — ビルドについては Dockerfile を参照してください。
• Windows はワンライナーインストーラーの正式な対象ではありません。Docker イメージまたは WSL を使用してください。

---

リポジトリの内容

ファイル	用途
Dockerfile	公開されている CLI から stdio イメージをビルドします。
server.json	公式 MCP Registry のマニフェスト（OCI パッケージ）。CI が公開時にバージョン／タグを書き換えます。
glama.json	Glama の自動インデックス作成に使用するメンテナーのメタデータ。
llms-install.md	LLM エージェント／ディレクトリクローラー向けのインストール手順。
.github/workflows/publish.yml	ghcr.io/willnewby/simpletel-mcp をビルドしてプッシュし、レジストリに公開します。

ライセンス

MIT — LICENSE を参照してください。