just-mcp

Transform justfiles into AI-accessible automation tools through the Model Context Protocol

just-mcp bridges justfiles and Coding Agents by exposing justfile recipes as dynamically discoverable MCP tools.

This enables AI assistants to understand, explore, and execute a project's common development workflows similar to how a human would.

<img width="676" height="331" alt="just-mcp" src="https://github.com/user-attachments/assets/c1222e9b-e440-4e7e-ab8c-629e727d1849" />

Quick Start

1. Install just-mcp

# Using cargo-binstall (fastest - downloads pre-built binary)
cargo binstall --git https://github.com/toolprint/just-mcp just-mcp

# Or download latest release
curl -L https://github.com/toolprint/just-mcp/releases/latest/download/just-mcp-$(uname -m)-$(uname -s).tar.gz | tar xz
sudo mv just-mcp /usr/local/bin/

2. Configure your Agent (see MCP Client Setup below)

3. Use the Slash Command:

/just:do-it build the project

It will find the appropriate justfile task to run as an MCP Tool.

That's it. Your AI can now use your justfile tasks.

MCP Client Setup

<details> <summary><strong>Claude Code</strong></summary>

claude mcp add -s user -t stdio just -- just-mcp

Or manually add to ~/.claude.json:

{
  "mcpServers": {
    "just": {
      "type": "stdio", 
      "command": "just-mcp"
    }
  }
}

Verification: Start a new session and check /mcp for 'just' and view details to see how many tools loaded.

</details> <details> <summary><strong>Claude Desktop</strong></summary>

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "just": {
      "command": "just-mcp", 
      "args": ["--watch-dir", "/Users/username/workspace/your-project-dir"],
    }
  }
}

Verification: Restart Claude Desktop, check the settings button for custom connection tools.

</details> <details> <summary><strong>Cline (VS Code Extension)</strong></summary>

1. Click Cline icon → MCP Servers → Configure MCP Servers
2. Add configuration:

{
  "mcpServers": {
    "just": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "just-mcp",
      "args": [
        "-w",
        "/Users/username/your-project-dir"
      ]
    }
}

Verification: Look for MCP server status in Cline's interface.

NOTE: Since cline runs outside of your current project working directory you MUST specify the watch-dir or use the admin tools at runtime to ask Cline to switch the watch-dir for you.

</details>

Key Features

🔍 Smart Justfile Discovery

• Real-time monitoring with hot reloading
• Defaults to use the current project root directory to look for your justfile
• Dynamic tool generation from your tasks

📝 Advanced Parsing

• AST-based parser using Tree-sitter for complete syntax support
• Parameter documentation from comments: # {{param}}: description
• Three-tier fallback: AST → CLI → Regex for maximum compatibility

🛡️ Security First

• Input validation prevents command injection
• Configurable timeouts and resource limits
• Directory whitelisting and parameter sanitization

⚙️ Admin Tools

• admin_sync: Refresh tool registry
• admin_create_task: AI-assisted task creation with backup

🔍 Vector Search (Optional)

• Offline semantic search with local embeddings (no API keys)
• Natural language queries: "deploy to production"
• Cross-project discovery of similar automation patterns
• See Vector Search docs

Example Workflow

Given this justfile:

# Deploy the application
deploy env="prod":
  echo "Deploying to {{env}}"
  ./deploy.sh {{env}}

# Run tests with coverage
test coverage="false":
  cargo test {{if coverage == "true" { "--coverage" } else { "" }}}

Your AI assistant can:

• Discover: "What tasks are available?"
• Execute: "Deploy to staging" → runs deploy env="staging"
• Understand: Sees parameters, descriptions, and dependencies

Installation Options

Pre-built Binaries (Recommended)

Download from GitHub Releases:

# Linux x86_64
curl -L https://github.com/toolprint/just-mcp/releases/latest/download/just-mcp-x86_64-unknown-linux-gnu.tar.gz | tar xz

# Linux ARM64  
curl -L https://github.com/toolprint/just-mcp/releases/latest/download/just-mcp-aarch64-unknown-linux-gnu.tar.gz | tar xz

# macOS (Universal - works on Intel and Apple Silicon)
curl -L https://github.com/toolprint/just-mcp/releases/latest/download/just-mcp-universal2-apple-darwin.tar.gz | tar xz

From Source

git clone https://github.com/toolprint/just-mcp.git
cd just-mcp
just quickstart  # Complete setup + install

Or manually:

cargo install --path . --features all  # All features including vector search

Development

Setup

just quickstart     # Complete setup for new developers
just dev-setup      # Comprehensive development environment

Workspace Structure

• ./ - Main MCP server
• dev-tools/ - Performance analysis utilities

Common Commands

just build              # Build main server  
just build-dev-tools    # Build development utilities
just test               # Run tests
just check              # Format, lint, test (pre-commit)

Multi-Project Example

Monitor multiple projects with custom names:

just-mcp \
  --watch-dir ~/projects/api:backend \
  --watch-dir ~/projects/web:frontend \
  --watch-dir ~/infrastructure:infra

Tools will be available as:

• just_deploy@backend
• just_build@frontend
• just_apply@infra

Documentation

• Configuration Guide - Detailed setup for all MCP clients
• Vector Search - Semantic search with natural language
• Troubleshooting - Common issues and solutions
• Contributing - Development workflow and guidelines

Architecture

Justfile Watcher → AST Parser → Tool Registry → MCP Server → AI Assistant
     ↓                ↓             ↓            ↓
File Changes → Dynamic Updates → Real-time → Task Execution

Key Design Principles:

• Async-first: Tokio-based for concurrent operations
• Security-focused: All inputs validated, resources limited
• Hot-reload: File changes trigger automatic tool updates
• Zero-config: Works with existing justfiles

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick steps:

1. just quickstart - Set up development environment
2. Make your changes and add tests
3. just check - Ensure code quality
4. Submit a Pull Request

License

MIT License - see LICENSE for details.

Acknowledgments

• just - The command runner that inspired this project
• Model Context Protocol - Enabling AI-tool communication
• Anthropic - For developing the MCP standard

---

Need help? Check troubleshooting or open an issue on GitHub.