MCP Server for Perses

Perses 用 MCP サーバー

概要

Perses MCP サーバーは、LLM ホスト（OpenCode、Claude Desktop、VS Code、Cursor）が Perses アプリケーションと標準化された方法で連携できるようにするローカルの Model Context Protocol (MCP) サーバーです。

デモ

OpenCode

https://github.com/user-attachments/assets/03706209-abef-47f2-8067-67c723537750

はじめに

前提条件

• 実行中の Perses インスタンス
• MCP サーバーのバイナリ — リリースページ からダウンロードし、展開して実行可能にします：

  chmod +x /path/to/perses-mcp-server
  

1. 設定ファイルを作成する

YAML 設定ファイル（例：perses-mcp-config.yaml）を作成します。各認証方法の詳細については 認証 を参照してください。

# MCP transport mode: "stdio" or "http"
transport: stdio

# Address to listen on for HTTP transport (e.g., ":8000")
listen_address: ":8000"

# Restrict the server to read-only operations
read_only: false

# Comma-separated list of resources to register (if empty, all resources are registered)
resources: ""

# Perses server connection configuration
perses_server:
  url: "http://localhost:8080"

  # Authentication (choose one method):
  # It is recommended to use environment variables for sensitive values.
  # Refer the "Environment Variables" section.

  # Option 1: Basic authentication (login/password)
  # native_auth:
  #   login: "admin"
  #   password: "password"

  # Option 2: Bearer token (e.g., from `percli whoami --show-token`)
  # authorization:
  #   type: Bearer
  #   credentials: "<YOUR_TOKEN>"
  #   # credentials_file: "/path/to/token/file"  # Alternative: read token from file

  # TLS configuration (optional)
  # tls_config:
  #   ca_file: "/path/to/ca.pem"
  #   insecure_skip_verify: false

メモ

設定値は次の順序で解決されます（後のものが優先）：組み込みのデフォルト < YAML 設定ファイル < 環境変数。

利用可能なリソース

resources フィールドには、以下のリソース名を指定できます（大文字と小文字を区別しません、カンマ区切り）：

環境変数

YAML ファイルの設定値は、PERMCP_ プレフィックスを付けた環境変数で上書きできます。変数名は、各 YAML キーを大文字にし、ネストされたキーを _ で連結して生成されます。

たとえば、YAML パス perses_server.native_auth.password は PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD になります。

これは、設定ファイルに保存すべきでないパスワードやトークンなどの機密値に特に便利です。

環境変数が設定ファイルを上書きする方法の詳細については、Perses 設定ドキュメント を参照してください。

2. MCP サーバーをクライアントに追加する

標準設定はほとんどのクライアントで動作します:

{
  "mcpServers": {
    "perses-mcp": {
      "command": "<ABSOLUTE_PATH_TO_PERSES_MCP_BINARY>",
      "args": [
        "--config",
        "<ABSOLUTE_PATH_TO_CONFIG_YAML>"
      ]
    }
  }
}

ヒント

機密性の高い認証情報は、設定ファイルに保存するのではなく、環境変数として渡してください:

Basic 認証: PERMCP_PERSES_SERVER_NATIVE_AUTH_LOGIN と PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD

Bearer トークン: PERMCP_PERSES_SERVER_AUTHORIZATION_CREDENTIALS

完全なリストについては環境変数を参照してください。

{
  "mcp": {
    "perses": {
      "command": [
        "<ABSOLUTE_PATH_TO_PERSES_MCP_BINARY>",
        "--config",
        "<ABSOLUTE_PATH_TO_CONFIG_YAML>"
      ],
      "environment": {
        "PERMCP_PERSES_SERVER_NATIVE_AUTH_LOGIN": "{env:PERMCP_PERSES_SERVER_NATIVE_AUTH_LOGIN}",
        "PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD": "{env:PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD}"
      },
      "enabled": true,
      "type": "local"
    }
  }
}

claude mcp add --transport stdio \
  --env PERMCP_PERSES_SERVER_NATIVE_AUTH_LOGIN=<YOUR_LOGIN> \
  --env PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD=<YOUR_PASSWORD> \
  perses-mcp -- <ABSOLUTE_PATH_TO_PERSES_MCP_BINARY> --config <ABSOLUTE_PATH_TO_CONFIG_YAML>

{
  "mcpServers": {
    "perses-mcp": {
      "command": "<ABSOLUTE_PATH_TO_PERSES_MCP_BINARY>",
      "args": [
        "--config",
        "<ABSOLUTE_PATH_TO_CONFIG_YAML>"
      ],
      "env": {
        "PERMCP_PERSES_SERVER_NATIVE_AUTH_LOGIN": "<YOUR_LOGIN>",
        "PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD": "<YOUR_PASSWORD>"
      }
    }
  }
}

{
  "servers": {
    "perses-mcp": {
      "command": "<ABSOLUTE_PATH_TO_PERSES_MCP_BINARY>",
      "args": [
        "--config",
        "<ABSOLUTE_PATH_TO_CONFIG_YAML>"
      ],
      "env": {
        "PERMCP_PERSES_SERVER_NATIVE_AUTH_LOGIN": "<YOUR_LOGIN>",
        "PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD": "<YOUR_PASSWORD>"
      }
    }
  }
}

Streamable HTTP モード

Streamable HTTP モードでは、MCP サーバーが HTTP 経由で LLM ホストと通信できるようになります。これはリモートホスティングや、複数のクライアントが同じサーバーインスタンスに接続する場合に便利です。

詳細は MCP プロトコル仕様ドキュメントを参照してください。

設定ファイルで transport: http を設定します:

transport: http
listen_address: ":8000"
perses_server:
  url: "http://localhost:8080"
  native_auth:
    login: "admin"
    password: "password"

次に、MCP クライアントを HTTP エンドポイントに向けます:

{
  "servers": {
    "perses-http": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

認証

Perses インスタンスで MCP サーバーを認証する方法は 2 つあります。設定ファイルの perses_server の下に関連するブロックを追加してください。

Basic 認証 (ユーザー名/パスワード)

Perses のユーザー名とパスワードをそのまま使用します:

native_auth:
  login: "your-username"
  password: "your-password"

Bearer トークン (percli 経由)

1. percli をインストールし、Perses サーバーにログインします:

percli login <PERSES_SERVER_URL>

例えば、percli login https://demo.perses.dev

2. ログインに成功したら、トークンを取得します:

percli whoami --show-token

3. 設定ファイルでトークンを使用します:

authorization:
  type: Bearer
  credentials: "<YOUR_TOKEN>"

警告

Bearer トークンは、Perses サーバーの access_token_ttl 設定 (デフォルト: 15 分) に基づいて自動的に期限切れになります。これは Perses アプリの設定で変更できます。

コマンドラインでの使用方法

perses-mcp-server --config /path/to/config.yaml

ツール

メモ

読み取り専用モード (設定で read_only: true) で実行している場合、情報を取得するツールのみが利用可能です。すべての書き込み操作 (作成、更新、削除) は読み取り専用モードでは無効になります。

プロジェクト

ダッシュボード

ダッシュボードの設定については、Perses Dashboards を参照してください。

エフェメラルダッシュボード

エフェメラルダッシュボードは、TTL (time-to-live) を持つ一時的なダッシュボードです。有効期限が切れると自動的にクリーンアップされます。

エフェメラルダッシュボードの設定については、Perses EphemeralDashboard を参照してください。

データソース

データソースのクエリ

perses_query_project_datasource と perses_query_global_datasource は、Perses プロキシ経由で設定済みのデータソースバックエンドに HTTP リクエストを転送します。つまり:

• 認証情報は自動的に注入されます — Perses で設定されたデータソースのシークレット (Bearer トークン、Basic 認証、OAuth) はサーバー側で適用され、ツールの呼び出し元に公開されることはありません。
• 許可されたエンドポイントが強制されます — データソースの allowedEndpoints 設定で許可されたエンドポイントにのみ到達できます。
• method のデフォルトは GET です。GET と POST のみを受け付けます。
• path はデータソースからの相対エンドポイントパスです。たとえば Prometheus では /api/v1/query_range、Loki では /loki/api/v1/query_range です。
• query_params はクエリ文字列パラメータとして追加されるキー/値の文字列ペアのオブジェクトです。
• body は生の文字列ボディです (JSON または application/x-www-form-urlencoded)。ボディが指定された場合、Content-Type のデフォルトは application/json です。
• headers を使用すると、追加のリクエストヘッダーを渡せます。Authorization ヘッダーはツール入力では常にブロックされます。認証には Perses のシークレットを使用してください。
• レスポンスボディは、LLM のコンテキスト制限を超えないよう、1 MiB に制限されます。

例 — グローバルデータソース経由の Prometheus インスタントクエリ:

{
  "datasource_name": "my-prometheus",
  "method": "POST",
  "path": "/api/v1/query",
  "query_params": {
    "query": "up",
    "time": "2024-01-01T00:00:00Z"
  }
}

例 — プロジェクトデータソース経由の Prometheus レンジクエリ:

{
  "project": "my-project",
  "datasource_name": "my-prometheus",
  "method": "POST",
  "path": "/api/v1/query_range",
  "query_params": {
    "query": "rate(http_requests_total[5m])",
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-01T01:00:00Z",
    "step": "60"
  }
}

ロール

プラグイン

変数

ローカル開発

ソースからのビルド

MCP サーバーをソースコードからビルドしたい場合（開発またはコントリビューション目的）、ソースコードのルートディレクトリで次のコマンドを実行します。

make build

これにより、mcp-server という名前のバイナリを含む bin ディレクトリが作成されます。MCP サーバーの設定で使用するために、このバイナリの絶対パスをコピーしてください。

ライセンス

このコードは Apache 2.0 ライセンスの下でライセンスされています。