Kestra Plugin Explorer MCP Server

An MCP (Model Context Protocol) server that gives AI assistants direct access to the Kestra plugin ecosystem. It wraps the Kestra public API into LLM-friendly tools — structured, concise, and ready to be consumed in a conversation.

Why this exists

For Kestra users

Writing Kestra flows means juggling plugin names, class paths, property schemas, and YAML syntax. Today that requires tab-switching between the docs site, the plugin reference, and the blueprint gallery.

This MCP server puts all of that inside your AI assistant. Ask it to find the right plugin, show you the properties for io.kestra.plugin.aws.s3.Upload, or grab a blueprint — and it answers with exactly the information you need, already formatted for the conversation.

Concrete things it unlocks:

• "Which plugin handles Slack notifications?" — search finds it instantly, no docs browsing.
• "Show me the properties for the GCS Upload task" — task_schema returns a properties table, examples, and output docs.
• "Give me a starter flow for S3 ETL" — blueprints + get_blueprint_flow returns ready-to-use YAML.
• "What version is the AWS plugin?" — versions answers in one call.
• "What Kestra version does plugin-aws v2.0.0 target?" — plugin_versions fetches the full release history from GitHub with the associated Kestra version.

For the Kestra team

• Support & community: Point users to the MCP server so AI assistants can answer plugin questions accurately, reducing repetitive support questions.
• Dogfooding: Internal developers building flows get the same benefits — faster discovery, less context-switching.
• Accuracy: Responses come from the live API, not from training data that may be outdated. The assistant always sees current plugin versions, schemas, and blueprints.

MCP tools vs Skills vs other approaches

This project uses MCP tools. Here's how MCP compares to other AI integration approaches available in Claude Code, and when to combine them.

| Approach | What it is | Best for | Tradeoffs | |----------|-----------|----------|-----------| | MCP tools | Tools registered via the MCP protocol, callable by any MCP-compatible client. The AI decides when to call them. | Data access — fetching plugin info, schemas, blueprints on demand. Portable across clients. | Each call costs tokens. The AI must discover and choose the right tool. | | Skills (slash commands) | Prompt templates triggered by the user (e.g. /write-flow). Injected once into the conversation to guide multi-step behavior. | Opinionated workflows that orchestrate multiple tool calls with domain logic baked in. | User-initiated only. Tied to Claude Code (not portable to other MCP clients). | | CLAUDE.md | Static instructions loaded into every conversation automatically. | Project conventions, coding standards, always-on context. Zero cost per tool call. | Uses context window space. Not interactive — can't fetch live data. | | Hooks | Shell commands that run on events (before/after tool calls, on notifications). | Guardrails, auto-formatting, lint-on-save, notifications. | Not for data access. Can block tool execution if misconfigured. |

Combine them

These approaches work best together, each handling a different layer:

• MCP tools = data layer — fetch live plugin info, schemas, blueprints.
• Skills = workflow layer — encode multi-step recipes that call MCP tools under the hood.
• CLAUDE.md = conventions layer — tell the AI how your team writes flows, names tasks, structures projects.
• Hooks = guardrails layer — validate, format, or notify automatically.

Example: A /write-flow skill could prompt the AI to (1) call search to find the right plugins, (2) call task_schema to get property details, (3) generate a complete flow YAML following the conventions from CLAUDE.md — all from a single slash command.

Tools

| Tool | Description | |------|-------------| | list_plugins | List all plugins with name, group, categories, and task/trigger counts. Optional category filter (AI, BUSINESS, CLOUD, CORE, DATA, INFRASTRUCTURE). | | search | Full-text search across plugins, docs, blueprints, or blogs. Returns titles, class names, URLs, and highlighted matches. | | plugin_tasks | List all tasks, triggers, and conditions for a plugin, grouped by subpackage. Accepts short names (plugin-aws) or groups (io.kestra.plugin.aws). | | task_schema | Full documentation for a task class: markdown docs, properties table, YAML examples, and output schema. | | blueprints | Search flow blueprint templates with pagination. Returns id, title, description, tags, and included tasks. | | get_blueprint_flow | Get the raw YAML flow definition for a blueprint by id. | | versions | List current versions of all Kestra plugins. Optional filter by plugin name. | | plugin_versions | Full release history of a plugin from GitHub, with the Kestra version each release targets (from gradle.properties). |

Setup

Prerequisites

• Node.js 18+
• (Optional) GITHUB_TOKEN env variable — required for plugin_versions to avoid GitHub API rate limits. Without it, unauthenticated requests are limited to 60/hour.

Install & build

npm install
npm run build

Use with Claude Code

The fastest way to add this MCP server to Claude Code:

claude mcp add kestra-plugin-explorer node /absolute/path/to/kestra-plugin-explorer-mcp/dist/index.js

This registers the server for your current project. To make it available across all projects, add the -s user flag:

claude mcp add -s user kestra-plugin-explorer node /absolute/path/to/kestra-plugin-explorer-mcp/dist/index.js

Verify it's registered:

claude mcp list

Then start Claude Code and the tools are available immediately — just ask questions like "search for S3 plugins" or "show me the schema for io.kestra.plugin.aws.s3.Upload".

Configure in other MCP clients

Add to your MCP client configuration (e.g. claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "kestra-plugin-explorer": {
      "command": "node",
      "args": ["/absolute/path/to/kestra-plugin-explorer-mcp/dist/index.js"]
    }
  }
}

Test with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Example conversation flow

1. Discover — "List all cloud plugins" → list_plugins(category: "CLOUD")
2. Explore — "What tasks does the AWS plugin have?" → plugin_tasks(plugin: "plugin-aws")
3. Detail — "Show me how to use S3 Upload" → task_schema(cls: "io.kestra.plugin.aws.s3.Upload")
4. Template — "Find a blueprint for S3 ETL" → blueprints(query: "s3")
5. Use — "Get that flow" → get_blueprint_flow(id: "...")

Architecture

src/
  index.ts        — Server bootstrap, registers all tools
  api.ts          — HTTP client (kestraFetch / kestraFetchText) with timeout + error handling
  format.ts       — stripHtml, truncate, formatProperties, result helpers
  tools/
    list.ts       — list_plugins
    search.ts     — search
    tasks.ts      — plugin_tasks
    schema.ts     — task_schema
    blueprints.ts — blueprints + get_blueprint_flow
    versions.ts   — versions + plugin_versions

All tools return content: [{ type: "text", text }] — never raw JSON dumps. Responses are formatted as markdown with tables, headers, and code blocks for readability.