flink-mcp-server
It is a read-only MCP server for inspecting and diagnosing Apache Flink clusters through the JobManager REST API, Kubernetes, and optionally Prometheus.
List configured/discovered clusters and get fleet or cluster overviews, TaskManagers, cluster config, and uploaded JARs.
List jobs and inspect job details, exceptions, job config, metrics, checkpoint stats, backpressure, and per-vertex metrics.
Diagnose job health in one call (
diagnose_job) with ranked findings across state, tasks, exceptions, checkpoints, backpressure, and source lag.View savepoints, restore sources, and a time-ordered job timeline.
List log files and tail/filter JobManager or TaskManager logs with warning/error counts.
Discover Flink Kubernetes
FlinkDeployments and diagnose operator/pod health such as CrashLoopBackOff, OOMKilled, image pull errors, and unschedulable pods.Optionally use Prometheus trends/query tools when configured.
Work across multiple clusters via an optional
clusterargument; operations are read-only, bounded/redacted, and available over stdio or authenticated HTTP.
Provides read-only monitoring of Apache Flink clusters through a reachable JobManager REST endpoint. It exposes tools for cluster overview, job listing and details, exceptions, checkpoint statistics, backpressure, TaskManagers, job configuration and metrics, uploaded JARs, multi-cluster fleet overview, and one-call job diagnosis with ranked findings.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@flink-mcp-server diagnose the latest Flink job on prod and summarize the issues"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
flink-mcp-server
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_jobreturns ahealthy/degraded/criticalverdict 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_timelineof 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
GETrequests, and every tool carries the MCPreadOnlyHintannotation 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-serverOr 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 | iexInstaller 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-serverClaude 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 8000The 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 |
|
| JobManager REST endpoint |
| unset | Bearer token sent to Flink |
| unset | YAML with several clusters (example) |
|
|
|
| unset | Enables optional Prometheus trends and query tools |
|
|
|
| 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 |
| Configured and discovered clusters (names and redacted URLs), plus any |
| Every cluster in one call; unreachable ones report an error |
| Flink version, slots, TaskManagers, job counts by state |
| Slots and resources per TaskManager |
| JobManager configuration (secrets masked by Flink), filterable |
| Uploaded JARs and their entry classes |
Jobs
Tool | What it returns |
| Jobs with state and duration |
| State and per-vertex status and parallelism |
| Root exception and recent history, stack traces trimmed |
| Counts, failure rate, last completed and failed checkpoint |
| Per-vertex backpressured, busy and idle time |
| Metric values, or the catalogue of available metrics |
| Operator/task metrics per vertex (min/max/avg over subtasks); names may omit the operator prefix, e.g. |
| Job execution configuration |
| Savepoints, latest completed checkpoint, what the job was restored from |
| Time-ordered state changes, failures, checkpoints, savepoints, restores and Kubernetes events, with each source's coverage |
| Verdict plus ranked findings; with Prometheus, trends over |
Logs
Tool | What it returns |
| Log files of the JobManager or one TaskManager |
| Filtered tail (level or text; stack traces stay with their error) and warning/error counts |
Kubernetes (Flink Kubernetes Operator)
Tool | What it returns |
| Lifecycle, JobManager and job state, operator errors |
| Operator and pod health: CrashLoopBackOff, OOMKilled, image pull errors, unschedulable pods |
Prometheus (only when configured)
Tool | What it returns |
| 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
ordersjob restarting? Check exceptions and checkpoints.""Is
flink/ordershealthy 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_queryandprometheus_query_rangeare not scoped.clusteronly 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 |
| URL and port of the JobManager REST API; |
| Set |
TLS errors | Set |
| Configure the final URL; redirects are never followed |
Clients get | Send |
Clients get | Set |
No Kubernetes clusters listed |
|
Prometheus trends | Define a |
๐ 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 --versionIntegration 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 k8sLayout: 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 toolsbackpressureBRead-onlyIdempotent
Per-vertex backpressure (avg ms/s backpressured, busy, idle) for a job.
Inputs: job_id (required), cluster. Returns: result
checkpoint_statsCRead-onlyIdempotent
Checkpoint counts, failure rate, last completed/failed checkpoint.
Inputs: job_id (required), cluster. Returns: object
cluster_configARead-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_overviewCRead-onlyIdempotent
Flink version, TaskManager/slot counts and job counts by state.
Inputs: cluster. Returns: object
diagnose_deploymentARead-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_jobARead-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_overviewARead-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_logsARead-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_configCRead-onlyIdempotent
Execution configuration of a job.
Inputs: job_id (required), cluster. Returns: object
job_detailsCRead-onlyIdempotent
State and per-vertex status/parallelism of one job.
Inputs: job_id (required), cluster. Returns: object
job_exceptionsCRead-onlyIdempotent
Root exception and the most recent entries of the job's exception history.
Inputs: job_id (required), limit, cluster. Returns: object
job_metricsARead-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_timelineARead-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_clustersARead-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_flink_deploymentsCRead-onlyIdempotent
FlinkDeployments (Flink Kubernetes Operator) with lifecycle, JobManager and job state. Needs Kubernetes access (kubernetes section in the clusters file, or FLINK_KUBERNETES=true).
Inputs: namespace. Returns: result
list_jarsCRead-onlyIdempotent
JAR files uploaded to the cluster with their entry classes.
Inputs: cluster. Returns: result
list_jobsBRead-onlyIdempotent
All jobs (running and recently finished) with state and duration.
Inputs: cluster. Returns: result
list_log_filesARead-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_savepointsARead-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
taskmanagersCRead-onlyIdempotent
TaskManagers with slot usage and resources.
Inputs: cluster. Returns: result
vertex_metricsARead-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
Scored across 21 tools
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.
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.
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.
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
Related MCP Connectors
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Discover Frontier inference capabilities and read sanitized usage through read-only tools.
Read-only server insight: why a Linux server or K8s cluster is slow, failing or changed.
LLM API discovery: access conditions, dated costs, sampled checks and keyless configs. Read-only.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceExposes 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.-
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Apache Flink clusters via the SQL Gateway, allowing query execution, session management, and job control through MCP tools.8Apache 2.0
- AlicenseNot gradedqualityDmaintenanceProvides read-only monitoring of Apache Airflow DAGs, including listing active DAGs, fetching recent runs, and analyzing execution history and performance metrics.1MIT
- FlicenseNot gradedqualityDmaintenanceProvides 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.-