🌊🔍 用于 Apache Kafka 的 Lenses MCP 服务器 🔎🌊

Name: Lenses MCP Server
Author: lensesio

Python 3.12+ FastMCP MCP License: Apache 2.0

这是用于 Apache Kafka 的 Lenses MCP（模型上下文协议）服务器。Lenses 为构建连接到 Kafka 的实时应用程序的工程师提供了开发体验解决方案。它专为企业打造，并由强大的 IAM 和治理模型提供支持。

借助 Lenses，您可以跨多个 Kafka 和供应商资产查找、探索、转换、集成和复制数据。现在，通过此用于 Kafka 的 Lenses MCP 服务器，您的 AI 助手或代理即可获得所有这些功能。

观看演示视频，在漫步纽约街头的同时了解其工作原理！

立即尝试免费的 Lenses 社区版（受用户数量和企业功能限制）。Lenses CE 附带一个预配置的单代理 Kafka 集群，非常适合本地开发或演示。连接最多两个您自己的 Kafka 集群，然后使用自然语言与您的流数据进行交互。

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 创建虚拟环境，在其中安装项目依赖项，然后使用 FastMCP CLI 通过默认的 stdio 传输运行 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 服务器

Lenses 文档可在 Context7 上获取。使用 Context7 MCP 服务器是可选的，但强烈建议使用，并使用 use context7 调整您的提示词，以确保提供给 LLM 的文档是最新的。

6. 使用 Docker 运行

Lenses MCP 服务器以 Docker 镜像 lensesio/mcp 的形式提供。您可以根据用例以不同的传输模式运行它。

快速入门

使用 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`	Lenses 实例 URL，格式为 `[scheme]://[host]:[port]`。使用 `https://` 进行安全连接（自动使用 `wss://` 进行 WebSocket）
`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 处的服务器发送事件 (SSE) 端点

构建 Docker 镜像

要在本地构建 Docker 镜像：

docker build -t lensesio/mcp .

7. OAuth 2.1 身份验证

当设置了 MCP_ADVERTISED_URL 时，MCP 服务器将作为具有完整 RFC 7662 令牌内省功能的 OAuth 2.1 受保护资源运行。这取代了静态 LENSES_API_KEY 方法，为 HTTP 传输提供承载令牌身份验证，并将 TRANSPORT 默认为 http。

工作原理

身份验证流程涉及三个参与者：MCP 客户端、授权服务器（LENSES_ADVERTISED_URL 处的 Lenses HQ，默认为 LENSES_URL）以及此 MCP 服务器（资源服务器）。

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 之前会被拒绝。
令牌转发 — 有效令牌会通过 Authorization: Bearer <token> 转发到 Lenses API，以便 Lenses 可以执行自己的授权检查。

授权作用域

服务器在其受保护资源元数据中通告三个作用域：

作用域	描述
`read`	对 Lenses 资源（主题、环境、连接器等）的只读访问权限
`write`	创建和更新资源
`delete`	删除资源

作用域不会在内省级别全局强制执行 — 接受具有这些作用域的任何子集的令牌。可以使用 FastMCP 的 require_scopes 装饰器添加针对特定工具的作用域强制执行。

配置

在简单的部署中，只需要两个环境变量：

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 HQ（通过 LENSES_ADVERTISED_URL 访问）必须支持：

/.well-known/oauth-authorization-server 处的 OAuth 2.0 授权服务器元数据 (RFC 8414)
introspection_endpoint 处的 令牌内省 (RFC 7662)，且禁用客户端身份验证
用于客户端授权流程的 带 S256 的 PKCE (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