🌊🔍 Apache Kafka用 Lenses MCP Server 🔎🌊

Name: Lenses MCP Server
Author: lensesio

Python 3.12+ FastMCP MCP License: Apache 2.0

これはApache Kafka用のLenses MCP (Model Context Protocol) サーバーです。Lensesは、Kafkaに接続されたリアルタイムアプリケーションを構築するエンジニア向けの開発者エクスペリエンスソリューションを提供します。エンタープライズ向けに構築されており、強力なIAMおよびガバナンスモデルによって支えられています。

Lensesを使用すると、複数のKafkaおよびベンダー環境全体でデータを検索、探索、変換、統合、複製できます。このLenses MCP Server for Kafkaを通じて、AIアシスタントやエージェントからこのすべての機能にアクセスできるようになりました。

ニューヨークの街を歩きながら、解説と実際の動作をご覧ください！

無料のLenses Community Edition（ユーザー数やエンタープライズ機能に制限あり）で今すぐお試しください。Lenses CEには、ローカル開発やデモンストレーションに最適な、事前設定済みのシングルブローカーKafkaクラスターが付属しています。独自のKafkaクラスターを最大2つまで接続し、自然言語を使用してストリーミングデータとやり取りできます。

1. uvとPythonのインストール

依存関係の管理とプロジェクトのセットアップにはuvを使用します。uvがインストールされていない場合は、公式インストールガイドに従ってください。

このプロジェクトはPython 3.12を使用して構築されています。Pythonが正しくインストールされていることを確認するには、次のコマンドを実行してバージョンを確認してください。

uv run python --version

2. 環境変数の設定

環境ファイルの例をコピーします。

cp .env.example .env

.envを開き、Lensesインスタンスの詳細やLenses APIキーなどの必要な値を入力します。

3. Lenses APIキーの追加

IAMサービスアカウントを作成して、Lenses APIキーを作成します。APIキーを.envに変数名LENSES_API_KEYとして追加します。

4. 依存関係のインストールとサーバーの実行

uvを使用して仮想環境を作成し、プロジェクトの依存関係をインストールしてから、デフォルトのstdioトランスポートを使用してFastMCP CLIでMCPサーバーを実行します。

uv sync
uv run src/lenses_mcp/server.py

リモートサーバーとして実行するには、httpトランスポートを使用します。

uv run fastmcp run src/lenses_mcp/server.py --transport=http --port=8000

Claude Desktop、Gemini CLI、Cursorなどで実行するには、次のJSON設定を使用します。

{
  "mcpServers": {
    "Lenses.io": {
      "command": "uv",
      "args": [
        "run",
        "--project", "<ABSOLUTE_PATH_TO_THIS_REPO>",
        "--with", "fastmcp",
        "fastmcp",
        "run",
        "<ABSOLUTE_PATH_TO_THIS_REPO>/src/lenses_mcp/server.py"
      ],
      "env": {
        "LENSES_API_KEY": "<YOUR_LENSES_API_KEY>"
      },
      "transport": "stdio"
    }
  }
}

注: 一部のクライアントでは、コマンド内でuvへの絶対パスが必要になる場合があります。

5. オプションのContext7 MCP Server

LensesのドキュメントはContext7で入手できます。Context7 MCP Serverを使用し、LLMが利用できるドキュメントが最新であることを確認するためにuse context7でプロンプトを調整することを強くお勧めします（オプション）。

6. Dockerでの実行

Lenses MCPサーバーは、lensesio/mcpとしてDockerイメージで利用可能です。ユースケースに応じて、さまざまなトランスポートモードで実行できます。

クイックスタート

stdioトランスポート（デフォルト）でサーバーを実行します：

docker run \
   -e LENSES_API_KEY=<YOUR_API_KEY> \
   -e LENSES_URL=http://localhost:9991 \
   lensesio/mcp

HTTPトランスポートでサーバーを実行します（http://0.0.0.0:8000/mcpでリッスン）：

docker run -p 8000:8000 \
   -e LENSES_API_KEY=<YOUR_API_KEY> \
   -e LENSES_URL=http://localhost:9991 \
   -e TRANSPORT=http \
   lensesio/mcp

SSEトランスポートでサーバーを実行します（http://0.0.0.0:8000/sseでリッスン）：

docker run -p 8000:8000 \
   -e LENSES_API_KEY=<YOUR_API_KEY> \
   -e LENSES_URL=http://localhost:9991 \
   -e TRANSPORT=sse \
   lensesio/mcp

環境変数

変数	必須	デフォルト	説明
`LENSES_API_KEY`	はい (OAuth使用時を除く)	-	Lenses APIキー（IAMサービスアカウント経由で作成）
`LENSES_URL`	いいえ	`http://localhost:9991`	`[scheme]://[host]:[port]`形式のLensesインスタンスURL。安全な接続には`https://`を使用（自動的にWebSockets用に`wss://`を使用）
`TRANSPORT`	いいえ	`MCP_ADVERTISED_URL`が設定されている場合は`http`、それ以外は`stdio`	トランスポートモード: `stdio`、`http`、または`sse`
`PORT`	いいえ	`8000`	リッスンするポート（`http`または`sse`トランスポートでのみ使用）
`MCP_ADVERTISED_URL`	OAuthの場合は必須	-	クライアントから到達可能なこのMCPサーバーのパブリックベースURL。これを設定するとOAuthがオンになり、`TRANSPORT`のデフォルトが`http`になります（OAuth 2.1認証を参照）
`LENSES_ADVERTISED_URL`	いいえ	`LENSES_URL`	OAuthログイン用にMCPクライアントにアドバタイズされるパブリックLenses HQ URL。MCPサーバーが内部アドレスでLensesに到達するスプリットプレーン展開でのみオーバーライドしてください
`MCP_SCOPES`	いいえ	`read,write,delete`	保護されたリソースメタデータでアドバタイズされるカンマ区切りのOAuthスコープ
`INTROSPECTION_URL`	いいえ	`LENSES_ADVERTISED_URL`メタデータから検出	RFC 7662トークンイントロスペクションエンドポイントURLのオーバーライド
`INTROSPECTION_CACHE_TTL`	いいえ	`0` (無効)	イントロスペクション結果のキャッシュTTL（秒）

レガシー環境変数（後方互換性用）：

LENSES_API_HTTP_URL, LENSES_API_HTTP_PORT
LENSES_API_WEBSOCKET_URL, LENSES_API_WEBSOCKET_PORT

これらはLENSES_URLから自動的に導出されますが、明示的に設定してオーバーライドすることも可能です。

トランスポートエンドポイント

stdio: 標準入出力（ネットワークエンドポイントなし）
http: /mcpのHTTPエンドポイント
sse: /sseのServer-Sent Eventsエンドポイント

Dockerイメージのビルド

Dockerイメージをローカルでビルドするには：

docker build -t lensesio/mcp .

7. OAuth 2.1認証

MCP_ADVERTISED_URLが設定されている場合、MCPサーバーは完全なRFC 7662トークンイントロスペクションを備えたOAuth 2.1保護リソースとして実行されます。これは、HTTPトランスポートのベアラートークン認証に静的なLENSES_API_KEYアプローチを置き換え、TRANSPORTのデフォルトもhttpにします。

仕組み

認証フローには、MCPクライアント、認可サーバー（LENSES_ADVERTISED_URLのLenses HQ。デフォルトはLENSES_URL）、およびこのMCPサーバー（リソースサーバー）の3者が関与します。

MCP Client                    Auth Server                   MCP Server
    │                              │                             │
    │  1. GET /.well-known/        │                             │
    │     oauth-protected-resource │                             │
    │─────────────────────────────────────────────────────────►  │
    │  ◄── authorization_servers,                                │
    │      scopes_supported                                      │
    │                              │                             │
    │  2. POST /register (DCR)     │                             │
    │─────────────────────────────►│                             │
    │  ◄── client_id, secret       │                             │
    │                              │                             │
    │  3. /authorize + PKCE (S256) │                             │
    │─────────────────────────────►│                             │
    │  ◄── authorization_code      │                             │
    │                              │                             │
    │  4. POST /token              │                             │
    │─────────────────────────────►│                             │
    │  ◄── access_token            │                             │
    │                              │                             │
    │  5. MCP request + Bearer token                             │
    │─────────────────────────────────────────────────────────►  │
    │                              │  6. POST /oauth2/introspect │
    │                              │  ◄──────────────────────────│
    │                              │  ── active, scopes, exp ──► │
    │                              │                             │
    │  ◄── MCP response (or 401)                                 │
    │                              │                             │

ステップ1〜4は、MCPクライアントと認可サーバーによって処理されます。MCPサーバーは関与しません。

ステップ5〜6は、このサーバーがトークンを検証する場所です：

保護リソースメタデータ (RFC 9728) — RemoteAuthProviderが/.well-known/oauth-protected-resource/mcpを提供するため、クライアントは使用する認可サーバーと利用可能なスコープを検出できます。
自動検出 — 最初の着信リクエスト時に、DiscoveryTokenVerifierは{LENSES_ADVERTISED_URL}/.well-known/oauth-authorization-serverを遅延フェッチしてintrospection_endpointを検出します。エンドポイントURLはINTROSPECTION_URLを介して明示的に設定することもできます。
トークンイントロスペクション (RFC 7662) — 着信ベアラートークンごとに、検証者はクライアント認証なしでイントロスペクションエンドポイント（/oauth2/introspect）にPOSTします。認可サーバーは以下を返します：
- active — トークンが有効かどうか
- scope — 付与されたスコープ（例: read write）
- client_id — トークンの所有者
- exp — 有効期限のタイムスタンプ
非アクティブまたは期限切れのトークンは、Lenses APIに到達する前に拒否されます。
トークン転送 — 有効なトークンは、Lensesが独自の認可チェックを実行できるように、Authorization: Bearer <token>を介してLenses APIに転送されます。

認可スコープ

サーバーは、保護リソースメタデータで3つのスコープをアドバタイズします：

スコープ	説明
`read`	Lensesリソース（トピック、環境、コネクタなど）への読み取り専用アクセス
`write`	リソースの作成と更新
`delete`	リソースの削除

スコープはイントロスペクションレベルでグローバルに強制されるわけではありません。これらのスコープのサブセットを持つトークンは受け入れられます。ツールごとのスコープ強制は、FastMCPのrequire_scopesデコレーターを使用して追加できます。

設定

単純な展開では、2つの環境変数のみが必要です：

LENSES_URL=https://lenses.example.com
MCP_ADVERTISED_URL=http://localhost:8000

MCP_ADVERTISED_URLが設定されているときは常にTRANSPORTのデフォルトがhttpになるため、明示的に設定する必要はありません。LENSES_ADVERTISED_URLのデフォルトはLENSES_URLであるため、MCPサーバーが内部アドレスでLensesに到達し、クライアントがパブリックアドレスで到達するスプリットプレーン展開でのみ設定する必要があります：

# Split-plane: MCP server → Lenses over internal DNS,
# MCP clients → Lenses over the public URL
LENSES_URL=http://lenses-hq.internal:9991
LENSES_ADVERTISED_URL=https://lenses.example.com
MCP_ADVERTISED_URL=https://mcp.example.com

LENSES_ADVERTISED_URLを介して到達するLenses HQは、以下をサポートする必要があります：

/.well-known/oauth-authorization-serverでのOAuth 2.0認可サーバーメタデータ (RFC 8414)
クライアント認証を無効にしたintrospection_endpointでのトークンイントロスペクション (RFC 7662)
クライアント認可フロー用のPKCE with S256 (RFC 7636)

MCPサーバーは、トークンをイントロスペクトする際にクライアント資格情報を送信しません。 Lenses HQ側では、これには以下が必要です：

oauth2:
  authorizationServer:
    unauthenticatedIntrospection: true

Lenses HQの設定で。このフラグがないと、イントロスペクションエンドポイントはMCPサーバーの認証されていないPOSTを拒否し、すべてのベアラートークンが無効として拒否されます。

OAuthでの実行

# Local development
LENSES_URL=https://lenses.example.com \
MCP_ADVERTISED_URL=http://localhost:8000 \
uv run src/lenses_mcp/server.py

# Docker
docker run -p 8000:8000 \
   -e LENSES_URL=https://lenses.example.com \
   -e MCP_ADVERTISED_URL=http://localhost:8000 \
   lensesio/mcp

MCP_ADVERTISED_URLが設定されていない場合、サーバーは後方互換性のために静的なLENSES_API_KEYにフォールバックし、TRANSPORTのデフォルトはstdioになります。

Lenses MCP Server