Windmill MCP

Windmill MCP Server

Provides complete Windmill API access through MCP (Model Context Protocol) tools by leveraging Windmill's OpenAPI specification.

📘 New to this project? Check out the Quick Start Guide for a step-by-step introduction.

Features

• 500+ API Tools: Complete Windmill API coverage through MCP
• Auto-Generated: Stays in sync with latest Windmill releases
• Custom Overrides: Modifications persist across regenerations
• Version Management: Automatic version matching with your Windmill instance
• Comprehensive Testing: Unit and E2E tests against live Windmill

Quick Start

Installation

# Clone and build
git clone https://github.com/rothnic/windmill-mcp.git
cd windmill-mcp
npm install
npm run generate

See Installation Guide for detailed setup instructions.

Configuration

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "windmill": {
      "command": "node",
      "args": ["/absolute/path/to/windmill-mcp/src/runtime/index.js"],
      "env": {
        "WINDMILL_BASE_URL": "https://your-instance.windmill.dev",
        "WINDMILL_API_TOKEN": "your-api-token"
      }
    }
  }
}

OpenCode (.opencode/opencode.jsonc in your project):

{
  "mcp": {
    "windmill": {
      "type": "local",
      "command": ["node", "/absolute/path/to/windmill-mcp/src/runtime/index.js"],
      "environment": {
        "WINDMILL_BASE_URL": "https://your-instance.windmill.dev",
        "WINDMILL_API_TOKEN": "your-api-token"
      },
      "enabled": true
    }
  }
}

See Configuration Reference for all options.

Documentation

User Guides

• Quick Start Guide - Step-by-step introduction
• Installation Guide - Detailed setup instructions
• Usage Guide - How to use the MCP server
• Troubleshooting Guide - Common issues and solutions

Developer Documentation

• Development Setup - Contributing and development workflow
• Generator System - How code generation works
• Testing Guide - Running and writing tests
• Architecture - System architecture

Reference

• API Tools Reference - Complete list of available tools
• Configuration Reference - All configuration options
• JSON Schema Guide - Working with schemas

Project Planning

• Project Plan - Overall project roadmap
• Sprint Planning - Sprint tracking
• Agent Team Plan - AI agent workflows

Project Structure

windmill-mcp/
├── src/
│   ├── generator/      # OpenAPI spec fetching and generation orchestration
│   ├── overrides/      # Custom modifications that persist across generations
│   └── runtime/        # Runtime loader with version management
├── build/              # Generated MCP server code (gitignored)
├── tests/              # Test suite (unit and E2E)
├── docs/
│   ├── guides/         # User-facing guides
│   ├── development/    # Developer documentation
│   ├── reference/      # Technical references
│   └── planning/       # Project planning documents
└── scripts/            # Utility scripts

Development

Quick Development Setup

# Install dependencies
npm install

# Start local Windmill instance
npm run docker:dev

# Generate MCP server
npm run generate

# Run tests
npm test

See Development Setup for comprehensive instructions.

Common Commands

# Generation
npm run generate          # Complete generation workflow
npm run fetch-spec        # Fetch OpenAPI spec only

# Development
npm run dev              # Run the MCP server directly
npm run test:watch       # Run tests in watch mode

# Testing
npm test                 # Run all tests
npm run test:e2e        # E2E tests (requires Windmill)
npm run test:e2e:full   # Full E2E with automatic setup

# Docker
npm run docker:dev      # Start Windmill for development
npm run docker:logs     # View Windmill logs
npm run docker:clean    # Clean all data

# Quality
npm run lint            # Lint code
npm run validate        # Run all validations

Automated Releases

New Windmill versions are automatically published via GitHub Actions:

• Weekly Schedule: Mondays at midnight UTC
• Manual Trigger: Run workflow in GitHub Actions
• Auto-Testing: E2E tests before release
• Version Tagging: windmill-v{version}-mcp-{package}

See Usage Guide for details.

Contributing

We welcome contributions! Please see:

• Contributing Guidelines - How to contribute
• Development Setup - Dev environment setup
• Testing Guide - Writing tests

License

MIT - see LICENSE

Resources

• Windmill Documentation - Official Windmill docs
• Windmill API - API documentation
• Model Context Protocol - MCP specification
• OpenAPI MCP Generator - Generator tool

Status

Current Version: 0.1.0 (Pre-release)

• ✅ Complete API coverage (500+ tools)
• ✅ Automated version management
• ✅ Comprehensive testing
• ✅ CI/CD pipeline
• ⏳ NPM package publication (coming soon)

See Project Status for detailed status.