Skip to main content
Glama

flink-mcp-server

PyPI Python CI License

A read-only MCP server that lets an AI assistant inspect and diagnose Apache Flink clusters. It only needs a reachable JobManager REST API, so it works the same on bare metal, Docker, Kubernetes or YARN, on Windows, macOS and Linux. Output is summarized for LLMs instead of returning raw REST JSON.

What is Apache Flink? Apache Flink is an open-source framework and distributed engine for stateful computations over data streams (and batches): streaming pipelines, event-driven applications and analytics that run continuously and must be monitored. See the Flink documentation and the Flink Kubernetes Operator.

Community-maintained. Not an official Apache Flink project and not affiliated with or endorsed by the Apache Software Foundation. Apache, Apache Flink and the Flink logo are trademarks of the Apache Software Foundation.

โœจ Features

  • Diagnosis in one call: diagnose_job returns a healthy / degraded / critical verdict with ranked findings from state, tasks, exceptions, checkpoints and backpressure. A source it cannot read is reported as not assessed, never as healthy.

  • Logs, savepoints, timeline: filtered log tails, savepoints and restore history, and one time-ordered job_timeline of what happened to a job.

  • Many clusters: a clusters file, or automatic discovery of FlinkDeployments through the Flink Kubernetes Operator.

  • Optional Prometheus trends (restarts, failing checkpoints, sustained backpressure).

  • Read-only by construction: only GET requests, and every tool carries the MCP readOnlyHint annotation so clients can recognise it. Bounded responses, no redirects followed, credentials redacted. See Security.

  • stdio for local clients, authenticated Streamable HTTP for remote ones.

Related MCP server: flink-mcp

๐Ÿ“‹ Requirements

  • Python 3.10+ (or just uv, which fetches Python for you)

  • Network access to a Flink JobManager REST API (and, optionally, a Kubernetes API or Prometheus)

๐Ÿš€ Installation

Run it on demand with uv (Windows, macOS, Linux), nothing to install:

uvx flink-mcp-server

Or use the one-line installers. They install uv first if it is missing. They download and run a script, so read it first if you prefer (install.sh, install.ps1).

# macOS / Linux
curl -LsSf https://raw.githubusercontent.com/hakkiburakalks/flink-mcp-server/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/hakkiburakalks/flink-mcp-server/main/install.ps1 | iex

Installer options: register with Claude Code and set the cluster URL (sh -s -- --claude-code --url http://localhost:8081 / -ClaudeCode -Url ...), or remove everything (--uninstall / -Uninstall). Set FLINK_MCP_SOURCE to install something other than the PyPI release, e.g. git+https://github.com/hakkiburakalks/flink-mcp-server.

๐ŸŽฏ Quick start

Claude Code:

claude mcp add flink -e FLINK_REST_URL=http://localhost:8081 -- uvx flink-mcp-server

Claude Desktop, Cursor and other clients (mcpServers in their JSON config):

{
  "mcpServers": {
    "flink": {
      "command": "uvx",
      "args": ["flink-mcp-server"],
      "env": { "FLINK_REST_URL": "http://localhost:8081" }
    }
  }
}

Then ask: "Which jobs are running, and is orders-enrichment healthy?"

Remote access (Streamable HTTP)

FLINK_MCP_AUTH_TOKEN=change-me flink-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

The endpoint is http://<host>:8000/mcp; clients send Authorization: Bearer <token>. On a non-loopback bind without a token, a random one is generated and printed to stderr. The server speaks plain HTTP, so put a TLS-terminating proxy in front of it. Details in Security.

๐Ÿ”ง Configuration

All optional. The most common settings:

Variable

Default

Meaning

FLINK_REST_URL

http://localhost:8081

JobManager REST endpoint

FLINK_REST_TOKEN

unset

Bearer token sent to Flink

FLINK_CLUSTERS_FILE

unset

YAML with several clusters (example)

FLINK_KUBERNETES

false

true discovers FlinkDeployments

PROMETHEUS_URL

unset

Enables optional Prometheus trends and query tools

FLINK_MCP_TRANSPORT

stdio

stdio or streamable-http

FLINK_MCP_AUTH_TOKEN

unset

Bearer token required on every HTTP request

Full reference: docs/configuration.md.

Several clusters. Copy clusters.example.yaml, set FLINK_CLUSTERS_FILE, and pass cluster: "prod" to any tool (omitted = default cluster). Prefer token_env over token so secrets stay out of the file.

Kubernetes. FLINK_KUBERNETES=true uvx flink-mcp-server turns every FlinkDeployment into a cluster named <namespace>/<name>, using your kubeconfig (or the pod's service account). Needs only the read-only role in examples/kubernetes-rbac.yaml. See docs/kubernetes.md.

Prometheus (optional). PROMETHEUS_URL=http://prometheus:9090 adds trends to diagnose_job and two raw PromQL tools. Without it nothing changes. See docs/prometheus.md, including the limits of the trends.

๐Ÿ› ๏ธ Available tools

22 tools (20 always, 2 only when Prometheus is configured). Every per-cluster tool accepts an optional cluster argument.

Clusters and fleet

Tool

What it returns

list_clusters

Configured and discovered clusters (names and redacted URLs), plus any discovery_error

fleet_overview

Every cluster in one call; unreachable ones report an error

cluster_overview

Flink version, slots, TaskManagers, job counts by state

taskmanagers

Slots and resources per TaskManager

cluster_config

JobManager configuration (secrets masked by Flink), filterable

list_jars

Uploaded JARs and their entry classes

Jobs

Tool

What it returns

list_jobs

Jobs with state and duration

job_details

State and per-vertex status and parallelism

job_exceptions

Root exception and recent history, stack traces trimmed

checkpoint_stats

Counts, failure rate, last completed and failed checkpoint

backpressure

Per-vertex backpressured, busy and idle time

job_metrics

Metric values, or the catalogue of available metrics

vertex_metrics

Operator/task metrics per vertex (min/max/avg over subtasks); names may omit the operator prefix, e.g. currentFetchEventTimeLag

job_config

Job execution configuration

list_savepoints

Savepoints, latest completed checkpoint, what the job was restored from

job_timeline

Time-ordered state changes, failures, checkpoints, savepoints, restores and Kubernetes events, with each source's coverage

diagnose_job

Verdict plus ranked findings; with Prometheus, trends over history

Logs

Tool

What it returns

list_log_files

Log files of the JobManager or one TaskManager

get_logs

Filtered tail (level or text; stack traces stay with their error) and warning/error counts

Tool

What it returns

list_flink_deployments

Lifecycle, JobManager and job state, operator errors

diagnose_deployment

Operator and pod health: CrashLoopBackOff, OOMKilled, image pull errors, unschedulable pods

Prometheus (only when configured)

Tool

What it returns

prometheus_query / prometheus_query_range

Read-only PromQL with enforced limits. Not scoped to a Flink cluster; see Security

๐Ÿ’ฌ Example queries

  • "Give me an overview of all my Flink clusters."

  • "Why is the orders job restarting? Check exceptions and checkpoints."

  • "Is flink/orders healthy on Kubernetes? The REST API doesn't answer."

  • "What happened to this job in the last hour? Show the timeline."

  • "Show errors in the JobManager log from the last 200 lines."

  • "Which savepoint was this job restored from?"

๐Ÿ”’ Security

The server only reads, but what it reads (job names, configuration, exceptions, logs) can be sensitive. What it does and does not do:

  • Authentication is on for HTTP unless you pass --no-auth; tokens are compared in constant time. The HTTP transport is plain HTTP, so use a TLS proxy.

  • Tool arguments (job ids, namespaces, file names) are validated so they cannot leave their endpoint; redirects are never followed; responses, log reads, PromQL and concurrency are bounded; URL credentials and tokens are kept out of output and errors.

  • prometheus_query and prometheus_query_range are not scoped. cluster only picks the Prometheus connection; it does not limit the query to that Flink cluster and is not an authorization boundary. Use a read-only Prometheus token limited to what you will expose.

  • Logs and exceptions come from the cluster and may contain secrets or text aimed at the model.

  • Automated tests and scans reduce risk; they do not prove the server is free of vulnerabilities.

Full model, limits and what was checked: docs/security.md. Report problems per SECURITY.md.

๐Ÿ› Troubleshooting

Symptom

Check

Cannot reach Flink at ...

URL and port of the JobManager REST API; curl <url>/overview

HTTP 401/403

Set FLINK_REST_TOKEN (or token_env in the clusters file)

TLS errors

Set ca_cert for the cluster; insecure: true only for tests

redirect that was not followed

Configure the final URL; redirects are never followed

Clients get 401 over HTTP

Send Authorization: Bearer <token>; check the token printed at startup

Clients get 421 over HTTP

Set FLINK_MCP_ALLOWED_HOSTS to the name clients use (needed for --no-auth on a LAN bind, or to restrict names)

No Kubernetes clusters listed

list_clusters shows discovery_error; check kubeconfig, namespaces and RBAC

Prometheus trends unmapped / ambiguous

Define a selector per cluster; see docs/prometheus.md

๐Ÿ” Debugging

Inspect tools and responses with the MCP Inspector:

npx @modelcontextprotocol/inspector uvx flink-mcp-server

๐Ÿงช Development

uv sync --extra dev
uv run pytest -m "not integration and not k8s"     # unit tests, no services needed
uv run flink-mcp-server --version

Integration tests need Docker. They start Flink and Prometheus, and a kind cluster for Kubernetes:

docker compose -f tests/env/docker-compose.yml up -d
docker compose -f tests/env/docker-compose.yml exec jobmanager flink run -d /opt/flink/examples/streaming/StateMachineExample.jar
uv run pytest -m integration

bash tests/env/k8s/setup.sh && FLINK_MCP_K8S_TEST_DIR=tests/env/k8s/.out uv run pytest -m k8s

Layout: src/flink_mcp/ (server and clients), tests/ (unit tests; tests/env/ holds the integration environments), docs/ (reference), examples/ (Kubernetes RBAC).

๐Ÿ“ Notes

  • Roadmap: approval-gated operations and SQL Gateway are planned, not implemented.

  • Tested against Flink 1.20 and Prometheus 2.55.

๐Ÿ“„ License

Apache License 2.0. Copyright ยฉ 2026 Hakkฤฑ Burak AlkฤฑลŸ.

See LICENSE for the complete license and NOTICE for attribution.

Reproducible installation options

The installers default to the current PyPI release. Set FLINK_MCP_VERSION=0.4.4 to select an exact release; use FLINK_MCP_SOURCE for a local checkout or an explicitly selected development source instead. These settings are mutually exclusive. The uv bootstrap defaults to 0.12.1; FLINK_MCP_UV_VERSION selects another exact bootstrap version when uv is absent. Existing uv installations are used as-is. A package version pin does not pin all transitive dependencies.

For reviewable installation, download the installer from a release tag or commit, inspect it, then run the saved file. Piping a script from main directly into a shell trusts mutable remote code. Bootstrap scripts still trust the uv publisher and HTTPS; version pins alone do not verify script signatures. For a locked local environment use uv sync --locked (lockfile artifact hashes are verified by uv). Ordinary end-user installs resolve dependencies within pyproject.toml ranges.

Available Tools

21 tools
backpressureB
Read-onlyIdempotent

Per-vertex backpressure (avg ms/s backpressured, busy, idle) for a job.

Inputs: job_id (required), cluster. Returns: result

checkpoint_statsC
Read-onlyIdempotent

Checkpoint counts, failure rate, last completed/failed checkpoint.

Inputs: job_id (required), cluster. Returns: object

cluster_configA
Read-onlyIdempotent

JobManager configuration (secrets are masked by Flink). Use search to filter keys, e.g. "checkpoint" or "state.backend".

Inputs: search, cluster. Returns: object

cluster_overviewC
Read-onlyIdempotent

Flink version, TaskManager/slot counts and job counts by state.

Inputs: cluster. Returns: object

diagnose_deploymentA
Read-onlyIdempotent

Kubernetes/operator-level health of one FlinkDeployment: operator errors, JobManager state and its pods (CrashLoopBackOff, OOMKilled, image pull errors, unschedulable). Use diagnose_job for problems inside a running job.

Inputs: name (required), namespace (required). Returns: object

diagnose_jobA
Read-onlyIdempotent

One-call health verdict for a job: combines state, task status, exceptions, checkpoints, backpressure and source lag into ranked findings. Start here when asked "why is this job unhealthy/slow?". When Prometheus is configured it also reports trends over the last history (default "1h"; "off" to skip): restarts, checkpoint failures and durations, sustained backpressure. Those are observations with their metric and window, not causes; a Prometheus problem never changes the live diagnosis.

Inputs: job_id (required), cluster, history. Returns: object

fleet_overviewA
Read-onlyIdempotent

Overview of every configured cluster in one call; unreachable clusters are reported with an error instead of failing the whole call.

Inputs: no named parameters. Returns: object

get_logsA
Read-onlyIdempotent

Tail of a Flink log: the JobManager's, or one TaskManager's when taskmanager_id is given. level ("WARN", "ERROR", ...) keeps only entries at that level or above, each with its stack trace; search keeps entries containing the text (case-insensitive). file defaults to the newest *.log; see list_log_files. The result also counts the warnings and errors in the whole file, so a clean tail of a noisy file is not mistaken for a clean log.

Inputs: file, level, lines, search, +2 more. Returns: object

job_configC
Read-onlyIdempotent

Execution configuration of a job.

Inputs: job_id (required), cluster. Returns: object

job_detailsC
Read-onlyIdempotent

State and per-vertex status/parallelism of one job.

Inputs: job_id (required), cluster. Returns: object

job_exceptionsC
Read-onlyIdempotent

Root exception and the most recent entries of the job's exception history.

Inputs: job_id (required), limit, cluster. Returns: object

job_metricsA
Read-onlyIdempotent

Job-level metrics. Give names to read values; omit it to list the available metric ids (narrow them with search, e.g. "checkpoint"). Flink fetches metrics lazily, so right after a job starts the first answer can take a couple of seconds.

Inputs: job_id (required), names, search, cluster. Returns: object

job_timelineA
Read-onlyIdempotent

What happened to a job and when, oldest first: the latest time it entered each state, recorded failures (exception history), failed checkpoints, savepoints and restores, and, for Kubernetes clusters, operator and pod events. Flink keeps no event log, so the result lists its coverage limits and any source that could not be read; a restart is shown only when a recorded failure or restore proves it. Keeps the most recent limit events.

Inputs: job_id (required), limit, cluster. Returns: object

list_clustersA
Read-onlyIdempotent

Flink clusters from the config file and, if enabled, discovered in Kubernetes (names and URLs, never credentials). discovery_error explains a failed discovery.

Inputs: no named parameters. Returns: object

list_jarsC
Read-onlyIdempotent

JAR files uploaded to the cluster with their entry classes.

Inputs: cluster. Returns: result

list_jobsB
Read-onlyIdempotent

All jobs (running and recently finished) with state and duration.

Inputs: cluster. Returns: result

list_log_filesA
Read-onlyIdempotent

Log files of the JobManager, or of one TaskManager when taskmanager_id is given (ids come from taskmanagers).

Inputs: cluster, taskmanager_id. Returns: object

list_savepointsA
Read-onlyIdempotent

Savepoints of a job, the latest completed checkpoint, and what the job was restored from, each with its storage path. Use it to find where a job can be restarted from; paths are only present for savepoints and for checkpoints retained on cancellation.

Inputs: job_id (required), cluster. Returns: object

taskmanagersC
Read-onlyIdempotent

TaskManagers with slot usage and resources.

Inputs: cluster. Returns: result

vertex_metricsA
Read-onlyIdempotent

Operator/task metrics of a job's vertices (all of them, or one vertex_id from job_details), aggregated over subtasks as min/max/avg. Without names it lists the metric ids (narrow with search, e.g. "lag"). A name may omit the operator prefix: "currentFetchEventTimeLag" matches "Source__.currentFetchEventTimeLag".

Inputs: job_id (required), names, search, cluster, +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    B3.1/5.0

    Scored across 21 tools

    Disambiguation4/5

    Most tools target a distinct resource+granularity: job_metrics vs vertex_metrics, get_logs vs list_log_files, diagnose_job (in-job health) vs diagnose_deployment (Kubernetes/operator health) are explicitly delineated in their descriptions. The main overlap cluster is job_details / job_timeline / diagnose_job / cluster_overview, where a newcomer might hesitate, but descriptions steer toward diagnose_job as the entry point.

    Naming Consistency3/5

    A dominant noun-based convention exists (cluster_config, job_config, checkpoint_stats, backpressure, taskmanagers) with `list_` used for enumerations (list_jobs, list_jars, list_clusters). But it is inconsistently applied: `get_logs` is the sole `get_` verb, `taskmanagers` is a bare plural where siblings use `list_`, and `list_flink_deployments` mixes a vendor-specific noun into the pattern.

    Tool Count3/5

    21 tools is on the heavy side for a monitoring server and pushes toward the borderline band. The facets (cluster, job, metrics, logs, config, savepoints, Kubernetes operator) each justify tools, but a few (list_jars, cluster_config, job_config) are narrow and could be consolidated into a generic cluster/job inspection call.

    Completeness4/5

    The read-only diagnostics surface is thorough: state, exceptions, timeline, checkpoints, savepoints/restore origins, backpressure, metrics at both job and vertex level, logs, config, and Kubernetes/operator health. Gaps are around lifecycle actions a user might expect next (trigger savepoint, cancel/restart job, thread dump), so an agent can diagnose but never act.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Exposes Spark History Server metrics and metadata as tools for LLM-based analysis of Spark applications. It enables deep optimization of Spark jobs by providing access to job summaries, stage details, SQL execution plans, and executor performance.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with Apache Flink clusters via the SQL Gateway, allowing query execution, session management, and job control through MCP tools.
      8
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides read-only monitoring of Apache Airflow DAGs, including listing active DAGs, fetching recent runs, and analyzing execution history and performance metrics.
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides a read-only interface to Kubernetes clusters, enabling LLMs to list pods, get pod status and logs, fetch deployment manifests, and perform pod health analysis with resource trend tracking.
      -