Tempo MCP Server

アーカイブ済み！

このプロジェクトはアーカイブされました。Tempo 自体に組み込みの MCP サーバーがあります。問題や PR はTempo リポジトリに登録してください。

Tempo MCP サーバー

Grafana Tempo と統合する、Go ベースの Model Context Protocol（MCP）サーバー実装です。

概要

この MCP サーバーを使用すると、AI アシスタントは Grafana Tempo の分散トレースデータをクエリして分析できます。Model Context Protocol に準拠しており、Claude Desktop などの互換性のある AI クライアントで使用できるツール定義を提供します。

はじめに

前提条件

• Go 1.21 以降
• Docker と Docker Compose（ローカルテスト用）

ビルドと実行

サーバーをビルドして実行します。

# Build the server
go build -o tempo-mcp-server ./cmd/server

# Run the server
./tempo-mcp-server

または、Go で直接実行します。

go run ./cmd/server

サーバーは、次の 2 つの通信モードに対応しています。

1. Model Context Protocol（MCP）に準拠した標準入力／出力（stdin/stdout）
2. n8n などのツールと統合するための Server-Sent Events（SSE）エンドポイントを備えた HTTP サーバー

HTTP サーバーのデフォルトポートは 8080 ですが、SSE_PORT 環境変数で設定できます。

サーバーエンドポイント

HTTP モードで実行すると、サーバーは次のエンドポイントを公開します。

• SSE エンドポイント：http://localhost:8080/sse - リアルタイムのイベントストリーミング用
• MCP エンドポイント：http://localhost:8080/mcp - MCP プロトコルのメッセージング用

Docker のサポート

Docker を使用して MCP サーバーをビルドし、実行できます。

# Build the Docker image
docker build -t tempo-mcp-server .

# Run the server
docker run -p 8080:8080 --rm -i tempo-mcp-server

または、Docker Compose を使用して完全なテスト環境を構築できます。

# Build and run with Docker Compose
docker-compose up --build

プロジェクト構成

.
├── cmd/
│   ├── server/       # MCP server implementation
│   └── client/       # Client for testing the MCP server
├── internal/
│   └── handlers/     # Tool handlers
├── pkg/
│   └── utils/        # Utility functions and shared code
└── go.mod            # Go module definition

MCP サーバー

Tempo MCP サーバーは Model Context Protocol（MCP）を実装し、次のツールを提供します。

Tempo クエリツール

tempo_query ツールを使用すると、Grafana Tempo のトレースデータをクエリできます。

• 必須パラメーター：
  • query：Tempo クエリ文字列（例：{service.name="frontend"}、{duration>1s}）
• 任意のパラメーター：
  • url：Tempo サーバーの URL（デフォルト：TEMPO_URL 環境変数の値、または http://localhost:3200）
  • start：クエリの開始時刻（デフォルト：1 時間前）
  • end：クエリの終了時刻（デフォルト：現在）
  • limit：返すトレースの最大数（デフォルト：20）
  • username：Basic 認証用のユーザー名（任意）
  • password：Basic 認証用のパスワード（任意）
  • token：認証用の Bearer トークン（任意）

環境変数

Tempo クエリツールは、次の環境変数に対応しています。

• TEMPO_URL：リクエストで指定されていない場合に使用するデフォルトの Tempo サーバー URL
• SSE_PORT：HTTP/SSE サーバーのポート（デフォルト：8080）

テスト

./run-client.sh tempo_query "{resource.service.name=\\\"example-service\\\"}"

Claude Desktop での使用

Tempo クエリツールを追加するには、この MCP サーバーを Claude Desktop で使用できます。次の手順に従ってください。

1. サーバーまたは Docker イメージをビルドします
2. Claude Desktop の設定ファイルにサーバーを追加し、使用するように設定します

Claude Desktop の設定例：

{
  "mcpServers": {
    "temposerver": {
      "command": "path/to/tempo-mcp-server",
      "args": [],
      "env": {
        "TEMPO_URL": "http://localhost:3200"
      },
      "disabled": false,
      "autoApprove": ["tempo_query"]
    }
  }
}

Docker の場合：

{
  "mcpServers": {
    "temposerver": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "TEMPO_URL=http://host.docker.internal:3200", "tempo-mcp-server"],
      "disabled": false,
      "autoApprove": ["tempo_query"]
    }
  }
}

Claude Desktop の設定ファイルは次の場所にあります。

• macOS の場合：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows の場合：%APPDATA%\Claude\claude_desktop_config.json
• Linux の場合：~/.config/Claude/claude_desktop_config.json

Cursor での使用

Tempo MCP サーバーを Cursor エディターに統合することもできます。その場合は、次の設定を Cursor の設定に追加します。

{
  "mcpServers": {
    "tempo-mcp-server": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "TEMPO_URL=http://host.docker.internal:3200", "tempo-mcp-server:latest"]
    }
  }
}

n8n での使用

n8n で Tempo MCP サーバーを使用するには、MCP Client Tool ノードを使って接続できます。

1. n8n ワークフローに MCP Client Tool ノードを追加します

2. 次のパラメーターを使ってノードを設定します。

   • SSE Endpoint：http://your-server-address:8080/sse（実際のサーバーアドレスに置き換えてください）
   • Authentication：必要に応じて適切な認証を選択します
   • Tools to Include：AI Agent に公開する Tempo ツールを選択します

3. Tempo のクエリ機能を使用する AI Agent ノードに、MCP Client Tool ノードを接続します

ワークフローの例： トリガー → MCP Client Tool（Tempo サーバー）→ AI Agent（Claude）

使用例

設定が完了したら、次のようなクエリを使って Claude でツールを利用できます。

• 「Tempo に {duration>1s} というクエリを使ってトレースを問い合わせる」
• 「{service.name=\"frontend\"} というクエリを使って Tempo からフロントエンドサービスのトレースを検索する」
• 「{http.status_code=500} を使って Tempo から最新のトレースを50件表示する」

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。