🌊🔍 Lenses MCP Server for Apache Kafka 🔎🌊

This is the Lenses MCP (Model Context Protocol) server for Apache Kafka. Lenses offers a developer experience solution for engineers building real-time applications connected to Kafka. It's built for the enterprise and backed by a powerful IAM and governance model.

With Lenses, you can find, explore, transform, integrate and replicate data across a multi-Kafka and vendor estate. Now, all this power is accessible through your AI tools and AI Agents via MCP, bringing real-time context into your agentic engineering workflows.

The quickest way to try the MCP server is with the free Lenses Community Edition, which runs Lenses MCP Server as a remote MCP server and comes with a pre-configured single broker Kafka cluster with demo data, ideal for local development or evaluation (steps here).

1. Install uv and Python

We use uv for dependency management and project setup. If you don't have uv installed, follow the official installation guide.

This project has been built using Python 3.12 and to make sure Python is correctly installed, run the following command to check the version.

uv run python --version

2. Configure Environment Variables

Copy the example environment file and configure it based on your authentication method:

cp .env.example .env

Required variables depend on your authentication choice:

For OAuth (recommended): LENSES_URL and MCP_ADVERTISED_URL
For API Key (fallback): LENSES_URL and LENSES_API_KEY

3. OAuth 2.1 Authentication (Recommended)

OAuth 2.1 is the recommended authentication method for all Lenses MCP deployments. It provides secure, scope-based authorization without sharing static API keys.

How it works

OAuth 2.1 uses bearer tokens that are validated via RFC 7662 Token Introspection. The flow involves three participants:

MCP Client — Your AI tool (Claude, Cursor, etc.)
Authorization Server — Lenses HQ at LENSES_ADVERTISED_URL
MCP Server — This server (the resource server)

When you connect, the client automatically:

Discovers OAuth metadata from this server (/.well-known/oauth-protected-resource/mcp)
Registers itself with the authorization server
Initiates OAuth authorization (with PKCE) and gets an access token
Uses the token to authenticate requests to this MCP server

This server then validates the token with Lenses HQ before allowing access to Kafka resources.

Simple setup

To use OAuth, you should set OAUTH_ENABLED to true, then you only need to set two environment variables:

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

LENSES_URL — Your Lenses instance (used internally and as the OAuth authorization server)
MCP_ADVERTISED_URL — The public URL where this MCP server is reachable by clients

TRANSPORT automatically defaults to http when MCP_ADVERTISED_URL is set.

Advanced: split-plane deployments

If the MCP server reaches Lenses on an internal address but clients reach it on a public URL:

OAUTH_ENABLED=true
LENSES_URL=http://lenses-hq.internal:9991
LENSES_ADVERTISED_URL=https://lenses.example.com
MCP_ADVERTISED_URL=https://mcp.example.com

Authorization scopes

The server advertises three scopes:

Scope	Description
`read`	Read-only access to Lenses resources (topics, environments, connectors, etc.)
`write`	Create and update resources
`delete`	Delete resources

When you authenticate, you'll be prompted to grant these scopes. Your token will only grant the scopes you select.

Lenses HQ configuration

Lenses HQ must support OAuth 2.0 and token introspection. Ensure your Lenses HQ config includes:

oauth2:
  authorizationServer:
    unauthenticatedIntrospection: true

This allows the MCP server to validate tokens without client credentials.

4. Lenses API Key (Fallback)

For backward compatibility and testing, you can use a static API key instead of OAuth. This is not recommended for production but may be useful for local development or legacy systems.

Create a Lenses API key by provisioning an IAM Service Account in Lenses. Add the API key to .env:

LENSES_URL=https://lenses.example.com
LENSES_API_KEY=<YOUR_LENSES_API_KEY>

When using API key authentication, TRANSPORT defaults to stdio (local only) unless you explicitly set MCP_ADVERTISED_URL.

5. Running the Server Locally

First, install dependencies:

uv sync

With OAuth (Recommended)

Run with stdio transport (for local AI tools):

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

Or run with HTTP transport (for remote clients):

OAUTH_ENABLED=true \
LENSES_URL=https://lenses.example.com \
MCP_ADVERTISED_URL=http://localhost:8000 \
uv run fastmcp run src/lenses_mcp/server.py --transport=http --port=8000

To configure in Claude Desktop, Cursor, or similar tools:

{
  "mcpServers": {
    "Lenses": {
      "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": {
        "OAUTH_ENABLED": "true",
        "LENSES_URL": "https://lenses.example.com",
        "MCP_ADVERTISED_URL": "http://localhost:8000"
      },
      "transport": "stdio"
    }
  }
}

With API Key (Legacy)

Using a static API key:

LENSES_URL=https://lenses.example.com \
LENSES_API_KEY=<YOUR_LENSES_API_KEY> \
uv run src/lenses_mcp/server.py

Or with HTTP transport:

LENSES_URL=https://lenses.example.com \
LENSES_API_KEY=<YOUR_LENSES_API_KEY> \
uv run fastmcp run src/lenses_mcp/server.py --transport=http --port=8000

To configure in Claude Desktop, Cursor, or similar tools:

{
  "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_URL": "https://lenses.example.com",
        "LENSES_API_KEY": "<YOUR_LENSES_API_KEY>"
      },
      "transport": "stdio"
    }
  }
}

Note: Some clients may require the absolute path to uv in the command.

6. Running with Docker

The Lenses MCP server is available as a Docker image at lensesio/mcp. You can run it with OAuth (recommended) or API key authentication.

With OAuth (Recommended)

Stdio transport (for local AI tools):

docker run --rm -it \
  -e OAUTH_ENABLED=true \
  -e LENSES_URL=https://lenses.example.com \
  -e MCP_ADVERTISED_URL=http://localhost:8000 \
  lensesio/mcp

HTTP transport (for remote clients, listens on http://0.0.0.0:8000/mcp):

docker run --rm -it -p 8000:8000 \
  -e OAUTH_ENABLED=true \
  -e LENSES_URL=https://lenses.example.com \
  -e MCP_ADVERTISED_URL=http://localhost:8000 \
  -e TRANSPORT=http \
  lensesio/mcp

For split-plane deployments where the MCP server reaches Lenses internally but clients use a public URL:

docker run --rm -it -p 8000:8000 \
  -e OAUTH_ENABLED=true \
  -e LENSES_URL=http://lenses-hq.internal:9991 \
  -e LENSES_ADVERTISED_URL=https://lenses.example.com \
  -e MCP_ADVERTISED_URL=https://mcp.example.com \
  -e TRANSPORT=http \
  lensesio/mcp

With API Key (Legacy)

Stdio transport (for local AI tools):

docker run --rm -it \
  -e LENSES_API_KEY=<YOUR_API_KEY> \
  -e LENSES_URL=https://lenses.example.com \
  lensesio/mcp

HTTP transport (for remote clients, listens on http://0.0.0.0:8000/mcp):

docker run --rm -it -p 8000:8000 \
  -e LENSES_API_KEY=<YOUR_API_KEY> \
  -e LENSES_URL=https://lenses.example.com \
  -e TRANSPORT=http \
  lensesio/mcp

Environment Variables Reference

Variable	Required	Default	Description
`OAUTH_ENABLED`	No	`false`	Enables/disables OAuth
`LENSES_URL`	Yes	`http://localhost:9991`	Lenses instance URL in format `[scheme]://[host]:[port]`. Use `https://` for secure connections (automatically uses `wss://` for WebSockets)
`MCP_ADVERTISED_URL`	For OAuth	-	Public base URL of this MCP server as reachable by clients. Setting this enables OAuth and defaults `TRANSPORT` to `http`
`LENSES_API_KEY`	For API Key auth	-	Your Lenses API key (create via IAM Service Account). Only needed if not using OAuth
`TRANSPORT`	No	`http` if `MCP_ADVERTISED_URL` is set, else `stdio`	Transport mode: `stdio`, `http`
`PORT`	No	`8000`	Port to listen on (only used with `http` transport)
`LENSES_ADVERTISED_URL`	No	`LENSES_URL`	Public Lenses HQ URL advertised to MCP clients for OAuth. Override only in split-plane deployments
`MCP_SCOPES`	No	`read,write,delete`	Comma-separated OAuth scopes advertised in protected-resource metadata
`INTROSPECTION_URL`	No	Discovered from `LENSES_ADVERTISED_URL` metadata	Override for the RFC 7662 token introspection endpoint URL
`INTROSPECTION_CACHE_TTL`	No	`0` (disabled)	Cache TTL for introspection results in seconds

Legacy environment variables (for backward compatibility):

LENSES_API_HTTP_URL, LENSES_API_HTTP_PORT
LENSES_API_WEBSOCKET_URL, LENSES_API_WEBSOCKET_PORT

These are automatically derived from LENSES_URL but can be explicitly set to override.

Transport Endpoints

stdio: Standard input/output (no network endpoint)
http: HTTP endpoint at /mcp
sse: Server-Sent Events endpoint at /sse

Building the Docker Image Locally

To build the Docker image locally:

docker build -t lensesio/mcp .

7. Optional Context7 MCP Server

Lenses documentation is available on Context7. It is optional but highly recommended to use the Context7 MCP Server and adjust your prompts with use context7 to ensure the documentation available to the LLM is up to date.

Appendix: OAuth Flow Details

Token validation sequence

The MCP server validates bearer tokens using the following sequence:

Protected Resource Metadata (RFC 9728) — RemoteAuthProvider serves /.well-known/oauth-protected-resource/mcp so clients can discover which authorization server to use and what scopes are available.
Auto-Discovery — On the first incoming request, the DiscoveryTokenVerifier lazily fetches {LENSES_ADVERTISED_URL}/.well-known/oauth-authorization-server to discover the introspection_endpoint. The endpoint URL can also be set explicitly via INTROSPECTION_URL.
Token Introspection (RFC 7662) — For each incoming bearer token, the verifier POSTs to the introspection endpoint (/oauth2/introspect) without client authentication. The authorization server responds with:
- active — whether the token is valid
- scope — granted scopes (e.g. read write)
- client_id — the token's owner
- exp — expiration timestamp
Inactive or expired tokens are rejected before reaching the Lenses API.
Token Forwarding — Valid tokens are forwarded to the Lenses API via Authorization: Bearer <token> so Lenses can perform its own authorization checks.

Authorization scopes

The server advertises three scopes in its protected-resource metadata:

Scope	Description
`read`	Read-only access to Lenses resources (topics, environments, connectors, etc.)
`write`	Create and update resources
`delete`	Delete resources

Scopes are not enforced globally at the introspection level — a token with any subset of these scopes is accepted. Per-tool scope enforcement can be added using FastMCP's require_scopes decorator.

Configuration and Requirements

In a simple deployment, only two environment variables are required:

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

For split-plane deployments where the MCP server reaches Lenses on an internal address but clients use a public URL, set:

LENSES_URL=http://lenses-hq.internal:9991
LENSES_ADVERTISED_URL=https://lenses.example.com
MCP_ADVERTISED_URL=https://mcp.example.com

Lenses HQ must support:

OAuth 2.0 Authorization Server Metadata (RFC 8414) at /.well-known/oauth-authorization-server
Token Introspection (RFC 7662) at the introspection_endpoint, with client authentication disabled
PKCE with S256 (RFC 7636) for client authorization flows

The MCP server does not send client credentials when introspecting. Lenses HQ must be configured with:

oauth2:
  authorizationServer:
    unauthenticatedIntrospection: true

Without this setting, every bearer token will be rejected as invalid.

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
.github		.github
src/lenses_mcp		src/lenses_mcp
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🌊🔍 Lenses MCP Server for Apache Kafka 🔎🌊

Table of Contents

1. Install uv and Python

2. Configure Environment Variables

3. OAuth 2.1 Authentication (Recommended)

How it works

Simple setup

Advanced: split-plane deployments

Authorization scopes

Lenses HQ configuration

4. Lenses API Key (Fallback)

5. Running the Server Locally

With OAuth (Recommended)

With API Key (Legacy)

6. Running with Docker

With OAuth (Recommended)

With API Key (Legacy)

Environment Variables Reference

Transport Endpoints

Building the Docker Image Locally

7. Optional Context7 MCP Server

Appendix: OAuth Flow Details

Token validation sequence

Authorization scopes

Configuration and Requirements

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

🌊🔍 Lenses MCP Server for Apache Kafka 🔎🌊

Table of Contents

1. Install uv and Python

2. Configure Environment Variables

3. OAuth 2.1 Authentication (Recommended)

How it works

Simple setup

Advanced: split-plane deployments

Authorization scopes

Lenses HQ configuration

4. Lenses API Key (Fallback)

5. Running the Server Locally

With OAuth (Recommended)

With API Key (Legacy)

6. Running with Docker

With OAuth (Recommended)

With API Key (Legacy)

Environment Variables Reference

Transport Endpoints

Building the Docker Image Locally

7. Optional Context7 MCP Server

Appendix: OAuth Flow Details

Token validation sequence

Authorization scopes

Configuration and Requirements

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages