NiFiPilot — AI Copilot for Apache NiFi
MCP (Model Context Protocol) server for Apache NiFi 2.2.0. Lets AI agents inspect, build, and control NiFi flows safely and auditably via 17 ready-to-use tools.
What it does
NiFiPilot exposes Apache NiFi's REST API as MCP tools so any compatible AI agent can:
- Inspect running flows, processor states, queue depths, and system health
- Build process groups, processors, and connections from natural language
- Control start/stop individual processors or entire process groups
- Audit every action — every tool call is written to a structured JSON log
Full pipeline created by AI: GenerateFlowFile → UpdateAttribute → EvaluateJsonPath → LogAttribute → PutFile
NiFiPilot in VS Code — Claude executing MCP tools with NiFi canvas visible in real time
Features
- 17 tools across three categories: read (5), write (6), control (6)
- Readonly mode — write and control tools are blocked; safe for production monitoring
- Dry-run mode — preview write/control actions without executing them
- Structured audit log — every tool call logged with params, result, and timestamp
- Lazy authentication — JWT token acquired on first call, refreshed automatically on 401
- Transports — stdio (local clients) and SSE (Docker/remote)
- 37 unit tests — no live NiFi required
Quick start with Docker Compose
The bundled compose file starts NiFi 2.2.0 and the MCP server together.
# 1. Copy and edit the env file
cp .env.example .env
# Edit NIFI_PASSWORD (min 12 chars) and set MCP_MODE=full to allow write/control
# 2. Start both services
docker compose up --build
# 3. NiFi UI: https://localhost:8443 (first start takes ~2 min)
# MCP SSE: http://localhost:8000/sse
Connect any MCP-compatible client to the SSE endpoint:
{
"mcpServers": {
"nifi-mcp": { "url": "http://localhost:8000/sse" }
}
}
Manual installation
Requirements: Python 3.11+
# From source
git clone https://github.com/Giojacke/mcp-nifipilot
cd mcp-nifipilot
pip install .
Run in stdio mode (used by Claude Code, VS Code, Cursor):
NIFI_URL=https://localhost:8443 \
NIFI_USERNAME=admin \
NIFI_PASSWORD=your-password \
NIFI_VERIFY_SSL=false \
MCP_MODE=readonly \
nifi-mcp
Configuration
All settings come from environment variables (or a .env file in the working directory).
| Variable | Default | Description |
|---|---|---|
NIFI_URL |
https://localhost:8443 |
NiFi base URL |
NIFI_USERNAME |
admin |
NiFi username |
NIFI_PASSWORD |
(required) | NiFi password (min 12 chars for single-user auth) |
NIFI_VERIFY_SSL |
false |
Verify TLS certificate (true in production) |
MCP_MODE |
readonly |
readonly — read tools only; full — all tools |
MCP_AUDIT_LOG |
true |
Write JSON audit log |
MCP_AUDIT_LOG_PATH |
./logs/audit.log |
Path for the audit log file |
MCP_RATE_LIMIT |
60 |
Max tool calls per minute |
MCP_DRY_RUN |
false |
Describe write/control actions without executing |
MCP_TRANSPORT |
stdio |
stdio for local clients; sse for Docker |
MCP_HOST |
0.0.0.0 |
Bind host when MCP_TRANSPORT=sse |
MCP_PORT |
8000 |
Port when MCP_TRANSPORT=sse |
Tool reference
Read tools (always available)
| Tool | Description |
|---|---|
get_process_groups(group_id) |
List direct child process groups |
get_processors(group_id) |
List processors in a group with run status |
get_connections(group_id) |
List connections with queue depth |
get_flow_status(group_id) |
Running/stopped/invalid counts and throughput |
get_system_diagnostics() |
NiFi version, heap, CPU, uptime |
Write tools (require MCP_MODE=full)
| Tool | Description |
|---|---|
create_process_group(name, parent_group_id, x, y) |
Create a new process group |
create_processor(name, processor_type, group_id, x, y) |
Add a processor (full Java class name) |
update_processor(processor_id, name?, properties?, scheduling_period?) |
Update processor config |
create_connection(source_id, destination_id, group_id, relationships?, ...) |
Connect two components |
delete_processor(processor_id) |
Delete a stopped processor |
delete_process_group(group_id) |
Delete a stopped process group |
Control tools (require MCP_MODE=full)
| Tool | Description |
|---|---|
start_processor(processor_id) |
Start a processor |
stop_processor(processor_id) |
Stop a processor |
start_process_group(group_id) |
Start all processors in a group |
stop_process_group(group_id) |
Stop all processors in a group |
get_queue_status(connection_id) |
Queue depth and throughput |
purge_queue(connection_id) |
Drop all flowfiles from a queue |
Client setup
Claude Code (stdio)
The .mcp.json at the project root is pre-configured. Fill in your password:
{
"mcpServers": {
"nifi-mcp": {
"command": "nifi-mcp",
"env": {
"NIFI_URL": "https://localhost:8443",
"NIFI_USERNAME": "admin",
"NIFI_PASSWORD": "YOUR_PASSWORD",
"NIFI_VERIFY_SSL": "false",
"MCP_MODE": "readonly"
}
}
}
}
Claude Code (SSE — Docker stack running)
{
"mcpServers": {
"nifi-mcp": { "url": "http://localhost:8000/sse" }
}
}
VS Code
Install from VS Code Marketplace: NiFiPilot — AI Copilot for Apache NiFi
Copy .vscode/mcp.json (included) and fill in your password.
Cursor / Windsurf
Place the stdio config at ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).
Security model
| Concern | Mitigation |
|---|---|
| Credential exposure | All secrets via env vars — never hardcoded |
| Accidental writes | MCP_MODE=readonly blocks all write and control tools |
| Runaway changes | MCP_DRY_RUN=true describes actions without executing |
| Auditability | Every tool call writes a JSON entry to the audit log |
| Token expiry | ensure_authenticated() re-logins on 401 automatically |
| SSL in production | Set NIFI_VERIFY_SSL=true with a valid certificate |
Development
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests (no live NiFi needed)
pytest
# Lint and format
ruff check src tests
ruff format src tests
Tests mock nipyapi at the API class level — 37 tests, no live NiFi required. Integration tests can be added in tests/integration/ (excluded from the default test run).
Architecture
See ARCHITECTURE.md for design decisions and the C4 diagrams.
Roadmap
- Rate limiting enforcement (config exists, middleware pending)
-
NiFiClientas real façade (tools currently call nipyapi directly) - Integration tests against live NiFi
- Azure DevOps MCP bridge for CI/CD of NiFi flows
License
MIT
Metadata
Release files for nifipilot 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nifipilot-0.1.1.tar.gz | 2.9 MB | Without provenance | Details for nifipilot-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nifipilot-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for nifipilot-0.1.1-py3-none-any.whl |
Total release size: 2.9 MB
Release files / nifipilot-0.1.1.tar.gz
| Download URL | nifipilot-0.1.1.tar.gz |
|---|---|
| Size | 2.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fc2e9acfb12e13e108e1bfa36713a2122b945e14a61268564b9190aa3a80e57e
|
|
BLAKE2b-256 checksum How to use checksums |
ef07fb9f2a490bacd7211f30c68ab6a47f1d29710936fb31f0db9bc95b254734
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.9
|
Release files / nifipilot-0.1.1-py3-none-any.whl
| Download URL | nifipilot-0.1.1-py3-none-any.whl |
|---|---|
| Size | 15.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0bd28d526920a5afbbdf5ddbf1c6c53531d7f171802b7bd47e2e033582928b01
|
|
BLAKE2b-256 checksum How to use checksums |
82829f590222e1700e7e5818f1a5c4c8c08ac54db98931be85fc20e5b5c83c6f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.9
|
Security for nifipilot 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.