🌊🔍 Lenses MCP Server 🔎🌊

This is the MCP (Model Context Protocol) server for Lenses, a self-service DataOps tool for engineers building real-time applications with different flavours of Apache Kafka across multiple clusters. Explore, transform and join data in topics from different clusters using SQL, without the need for an additional database.

Try this with the free Lenses Community Edition (restricted by number of users and enterprise features, e.g. OAuth). Requires Lenses v6+.

Table of Contents

• 1. Install uv and Python
• 2. Configure Environment Variables
• 3. Add Lenses API Key
• 4. Install Dependencies and Run the Server
• 5. Optional Context7 MCP Server
• 6. Running with Docker

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.

cp .env.example .env

Open .env and fill in the required values such as your Lenses instance details and Lenses API key.

3. Add Lenses API Key

Create a Lenses API key by creating an IAM Service Account. Add the API key to .env with the variable name, LENSES_API_KEY.

4. Install Dependencies and Run the Server

Use uv to create a virtual environment, install the project dependencies in it and then run the MCP server with the FastMCP CLI using the default stdio transport.

uv sync
uv run src/lenses_mcp/server.py

To run as a remote server, use the http transport.

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

To run in Claude Desktop, Gemini CLI, Cursor, etc. use the following JSON configuration.

{
  "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"
    }
  }
}

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

5. 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.

6. Running with Docker

The Lenses MCP server is available as a Docker image at lensesio/mcp. You can run it with different transport modes depending on your use case.

Quick Start

Run the server with stdio transport (default):

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

Run the server with HTTP transport (listens on 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

Run the server with SSE transport (listens on 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

Environment Variables

Variable	Required	Default	Description
LENSES_API_KEY	Yes	-	Your Lenses API key (create via IAM Service Account)
LENSES_URL	No	http://localhost:9991	Lenses instance URL in format [scheme]://[host]:[port]. Use https:// for secure connections (automatically uses wss:// for WebSockets)
TRANSPORT	No	stdio	Transport mode: stdio, http, or sse
PORT	No	8000	Port to listen on (only used with http or sse transport)

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

To build the Docker image locally:

docker build -t lensesio/mcp .