Just MCP Server MCP Server
io.github.PromptExecution/just-mcp
Expose curated Justfile recipes via MCP for safe, deterministic LLM automation.
What this kind of tool is for
- Chain multi-step workflows across the other tools in this directory.
- Run a scheduled or triggered job instead of retyping the same request.
- Have your agent watch a feed, queue, or repo and act on new items.
How to compare servers like this
- Trigger model:
- Understand what starts the automation — a command, a schedule, or an event — before relying on it.
- Blast radius:
- Prefer tools that hand you a review point before an irreversible action runs.
- Chaining cost:
- Each chained step adds a failure point; keep critical paths on the fewest tools.
- Maintenance signal:
- Automations break quietly; a maintained tool is the difference between repair and rediscovery.
This page carries your copy-paste config: pick your MCP client in the install section on this page and use the copy button.
What is the Just MCP Server MCP server?
The Just MCP Server is a production-ready MCP server that integrates the Just command runner with AI assistants, enabling them to discover, execute, and introspect Justfile recipes through the standardized MCP protocol. It provides a safer, context-efficient alternative to raw bash access by abstracting commands through Justfiles, reducing hallucinations and protecting against unintended system modifications.
Just-mcp lets AI agents safely execute predefined tasks from Justfiles without needing to understand bash or build system complexity. Instead of giving LLMs unrestricted shell access, you curate recipes in a Justfile and expose them via MCP—the agent gets a clean, memoized list of available commands with parameters and documentation. This is especially valuable for agent automation, self-hosted models with limited context, and scenarios where safety and reproducibility matter.
How to install Just MCP Server
Copy-paste configuration for popular MCP clients.
{
"mcpServers": {
"just-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/promptexecution/just-mcp:0.1.5"
]
}
}
}Tools & capabilities
Tools this server exposes to the agent.
list_recipes— List all available recipes in the justfilerun_recipe— Execute a specific recipe with optional arguments and capture structured outputget_recipe_info— Get detailed information about a specific recipe, including parameters and documentationvalidate_justfile— Validate the justfile for syntax and semantic errors
Use cases
- Safely automate CI/CD pipelines and build tasks by exposing curated recipes to AI agents
- Execute multi-step development workflows (testing, building, deploying) without exposing raw shell commands
- Reduce LLM context consumption by providing pre-defined, discoverable commands instead of requiring agents to read and parse build files
- Enable self-hosted or small open-source models to reliably execute complex tasks with 8k–32k context limits
- Implement transparent logging and secondary safety checks by wrapping commands in Justfile recipes
Just MCP Server MCP server FAQ
Just-mcp exposes curated Justfile recipes to AI assistants via MCP. It's safer than raw bash because recipes are predefined and memoized, reducing hallucinations and protecting against accidental file deletion or system damage. It also saves LLM context by eliminating the need to read build files or bash scripts.
Yes, Just-mcp is open-source under the MIT license and free to use.
Add a configuration entry to your Claude Desktop MCP settings using one of the provided installation methods: npm (npx just-mcp --stdio), pip (uvx just-mcp --stdio), cargo (cargo install just-mcp), or Docker (docker run ghcr.io/promptexecution/just-mcp:latest --stdio).
No, Just-mcp does not require authentication. It runs locally and executes recipes from your Justfile in your project directory.
Just-mcp requires the Just command runner to be installed on your system. It runs on Linux, macOS, and Windows, and is available via npm, pip, cargo, Docker, or as a pre-built binary.
Yes, Just-mcp is designed to work well with self-hosted models and smaller open-source models (8k–32k context), as it provides a low-overhead abstraction that minimizes context consumption compared to raw bash access.
README (reference)
Source of truth, from the repository.
just-mcp
👋 A way to let LLMs speak Just
A production-ready MCP server that provides seamless integration with Just command runner, enabling AI assistants to discover, execute, and introspect Justfile recipes through the standardized MCP protocol.
🎯 Why Just + MCP = Better Agent Execution
Context-Saving Abstraction
If it isn't immediately obvious, the benefit of having LLMs use Just vs. bash is that running Just commands (via MCP) provides a context-saving abstraction where they don't need to waste context opening/reading bash files, Python scripts, or other build artifacts. The LLM via MCP simply gets the command, parameters, and hints - it's in their memory as "these are commands available to you."
Eliminates the Justfile Learning Curve
No more watching LLMs execute just -l to get command lists, inevitably start reading the justfile, then try to write justfile syntax (like it's a Makefile), corrupt the justfile, and create a bad experience. Just's evolving syntax simply doesn't have a large enough corpus in frontier models today - we need more popular repos with justfiles in the training dataset.
Safer Than Raw Bash Access
Just-mcp is fundamentally safer than bash. If you read HackerNews, there's a story at least once daily about operators whose LLMs start forgetting, hallucinating, and eventually breaking down - deleting files and doing nasty unwanted things. Giving LLMs unsupervised, unrestricted bash access without carefully monitoring context consumption is a recipe for disaster.
Using Justfile fixes that. Even if the LLM modifies its own justfile, the next context is memoized by the justfile (hopefully in an idempotent git repo). This abstraction shields the llm from the command line complexity where hallucinations or attention tracking the current working directory cause it to go over the rails and off the cliff.
Powerful Agent Execution Tool
Just-mcp is perfect for anybody doing agent execution:
- Ultra-low overhead - probably better than every other tool
- Human-friendly - justfiles are easy for humans and low overhead for LLMs
- Quick and dirty - while some prefer full Python FastAPI servers, just-mcp is just easy-as
- sm0l model friendly - works great with self-hostable GPU/CPU open source models with 8k-32k context limits
Built-in Safety Patterns
Just has useful patterns for introducing:
- Transparent logging without distracting the agent
- Secondary model inspection - use sm0l models to scan commands asking "is this harmful?" before execution
- Python decorator-like patterns for command validation
- Idempotent execution backed by git repos
b00t
b00t mcp create just-mcp -- bash just-mcp --stdio "${REPO_ROOT}"
b00t mcp export just-mcp
🚀 Current Status: 67% Complete (8/12 core tasks)
✅ Implemented Features
- 🏗️ Complete MCP Server - Full rmcp 0.3.0 integration with MCP 2024-11-05 protocol
- 📋 Recipe Discovery - Parse and list all available Justfile recipes
- ⚡ Recipe Execution - Execute recipes with parameters and capture structured output
- 🔍 Recipe Introspection - Get detailed recipe information, parameters, and documentation
- ✅ Justfile Validation - Syntax and semantic validation with error reporting
- 🌍 Environment Management - Comprehensive .env file support and variable expansion
- 🧪 Full Test Coverage - 33 passing tests across integration and unit test suites
🎯 MCP Tools Available
list_recipes- List all available recipes in the justfilerun_recipe- Execute a specific recipe with optional argumentsget_recipe_info- Get detailed information about a specific recipevalidate_justfile- Validate the justfile for syntax and semantic errors
🏃 Quick Start
Installation
Choose your preferred installation method:
npm (JavaScript/TypeScript)
# Install globally
npm install -g just-mcp
# Or use with npx (no installation required)
npx just-mcp --stdio
pip (Python)
# Install with pip
pip install just-mcp
# Or use with uvx (recommended)
uvx just-mcp --stdio
Cargo (Rust)
# Install from crates.io
cargo install just-mcp
# Or build from source
git clone https://github.com/promptexecution/just-mcp
cd just-mcp
cargo build --release
pkgx (pkgxdev)
pkgx just-mcp --stdio
pkgx downloads the platform-specific tarball that GitHub releases expose (just-mcp-*-*.tar.gz), extracts the executable into ${PKGX_DIR:-$HOME/.pkgx}/bin, and runs the CLI with the arguments you pass. Add that bin directory to your shell’s PATH if you need just-mcp available long-term. The packaging manifest lives in pkgx/projects/github.com/promptexecution/just-mcp/package.yml and mirrors the pkgxdev/pantry entry.
Using Docker
# Pull the latest image from GitHub Container Registry
docker pull ghcr.io/promptexecution/just-mcp:latest
# Run with Docker
docker run --rm -v $(pwd):/workspace ghcr.io/promptexecution/just-mcp:latest --stdio
# Build locally
docker build -t just-mcp:local .
docker run --rm -v $(pwd):/workspace just-mcp:local --stdio
Available Docker image tags:
latest- Latest stable releaseX.Y.Z- Specific version (e.g.,0.1.0)X.Y- Latest patch version (e.g.,0.1)X- Latest minor version (e.g.,0)
Claude Desktop Integration
Using npm/npx
Add to your Claude Desktop MCP configuration:
Using Binary
{
"mcpServers": {
"just-mcp": {
"command": "npx",
"args": ["-y", "just-mcp", "--stdio"]
}
}
}
Using pip/uvx
{
"mcpServers": {
"just-mcp": {
"command": "uvx",
"args": ["just-mcp", "--stdio"]
}
}
}
Using cargo or manual install
{
"mcpServers": {
"just-mcp": {
"command": "/path/to/just-mcp",
"args": ["--stdio"]
}
}
}
Using Docker
{
"mcpServers": {
"just-mcp": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v",
"${workspaceFolder}:/workspace",
"ghcr.io/promptexecution/just-mcp:latest",
"--stdio"
]
}
}
}
Usage Examples
# Run as MCP server
just-mcp --stdio
# Run in specific directory
just-mcp --directory /path/to/project --stdio
# Using Docker
docker run --rm -v $(pwd):/workspace ghcr.io/promptexecution/just-mcp:latest --stdio
🧪 Testing
Comprehensive Test Suite
# Run all tests (33 tests)
cargo test
# Run specific test suites
cargo test --test basic_mcp_test # Protocol compliance testing
cargo test --test mcp_integration_working # SDK integration testing
Test Architecture
basic_mcp_test.rs- Direct protocol compliance testing using raw JSON-RPCmcp_integration_working.rs- Type-safe SDK integration testing with rmcp client- Unit tests - 25+ tests covering parser, executor, validator, and environment modules
📚 Architecture
Project Structure
just-mcp/
├── src/main.rs # CLI binary
├── just-mcp-lib/ # Core library
│ ├── parser.rs # Justfile parsing
│ ├── executor.rs # Recipe execution
│ ├── validator.rs # Validation logic
│ ├── environment.rs # Environment management
│ └── mcp_server.rs # MCP protocol implementation
├── tests/ # Integration tests
└── justfile # Demo recipes
Tech Stack
- Rust 1.82+ with async/await support
- rmcp 0.3.0 - Official MCP SDK for Rust
- serde/serde_json - JSON serialization
- snafu - Structured error handling
- tokio - Async runtime
🔄 Development Roadmap
🎯 Next Priority Tasks (Remaining 33%)
- LSP-Style Completion System - Intelligent autocompletion for recipes and parameters
- Enhanced Diagnostics - Advanced syntax error reporting and suggestions
- Virtual File System - Support for stdin, remote sources, and in-memory buffers
- Release Preparation - Documentation, CI/CD, and crate publication
🚀 Future Enhancements
- Plugin system for custom recipe types
- Integration with other build tools
- Performance optimizations for large justfiles
- Advanced dependency visualization
📖 Usage Patterns
Recipe Execution
// List available recipes
await client.callTool("list_recipes", {});
// Execute recipe with parameters
await client.callTool("run_recipe", {
"recipe_name": "build",
"args": "[\"--release\"]"
});
// Get recipe information
await client.callTool("get_recipe_info", {
"recipe_name": "test"
});
Validation
// Validate justfile
await client.callTool("validate_justfile", {
"justfile_path": "./custom.justfile"
});
🤝 Contributing
This project follows the b00t development methodology:
- TDD Approach - Tests first, implementation second
- Feature Branches - Never work directly on main branch
- Structured Errors - Use snafu for error management
- Git Workflow - Clean commits with descriptive messages
Development Commands
just build # Build the project
just test # Run tests
just server # Start MCP server
just clean # Clean build artifacts
📄 License
This project is licensed under LICENSE.
🚀 Release Setup & CI/CD
✅ Completed Setup
Cocogitto & Conventional Commits
- Installed cocogitto for conventional commit enforcement
- Configured
cog.tomlwith proper commit types and changelog settings - Set up git hooks for commit message linting (
commit-msg) and pre-push testing
GitHub Actions CI/CD
- CI Pipeline (
ci.yml): Multi-platform testing (Ubuntu, Windows, macOS), formatting, clippy, commit linting - Release Pipeline (
release.yml): Automated versioning, changelog generation, GitHub releases, and crates.io publishing - Binary Builds (
build-binaries.yml): Cross-platform binary compilation for npm and pip packages - Container Pipeline (
container.yaml): Multi-platform Docker image builds (linux/amd64, linux/arm64) pushed to GitHub Container Registry
Docker Images
- Multi-platform builds for
linux/amd64andlinux/arm64 - Minimal image size using static musl binaries and scratch base image
- Automatic tagging with semantic versioning (major, major.minor, major.minor.patch, latest)
- Published to GitHub Container Registry (ghcr.io)
- Integrated with release workflow for automatic deployment
Crates.io Preparation
- Updated both
Cargo.tomlfiles with complete metadata (description, keywords, categories, license, etc.) - Added proper exclusions for development-only files
- Verified MIT license is in place
Documentation & Structure
- README.md is production-ready with installation and usage instructions
- Created initial
CHANGELOG.mdfor release tracking - Updated
.gitignorewith Rust-specific entries
🚀 Production Deployment
Development Workflow:
- All commits must follow conventional commit format (enforced by git hooks)
- Use
feat:,fix:,docs:, etc. prefixes for automatic versioning - Push to
mainbranch triggers automated releases and crates.io publishing - Library tests pass ✅ (25/25) with comprehensive test coverage
Release Process:
- Automated Versioning: Cocogitto analyzes commit messages for semantic versioning
- GitHub Releases: Automatic changelog generation and GitHub release creation
- Binary Distribution: Pre-built binaries for Linux (x86_64, aarch64), macOS (x86_64, aarch64), and Windows (x86_64)
- Crates.io Publishing: Library crate (
just-mcp-lib) publishes first, then binary crate (just-mcp) - npm Publishing: Wrapper package for easy Node.js/TypeScript integration
- PyPI Publishing: Python wrapper package for pip/uvx installation
- CI/CD Pipeline: Multi-platform testing (Ubuntu, Windows, macOS) with formatting and clippy checks
Installation Methods:
# npm (JavaScript/TypeScript ecosystems)
npm install -g just-mcp
# or
npx just-mcp --stdio
# pip (Python ecosystems)
pip install just-mcp
# or
uvx just-mcp --stdio
# cargo (Rust ecosystem)
cargo install just-mcp
# Download pre-built binaries
wget https://github.com/promptexecution/just-mcp/releases/latest/download/just-mcp-x86_64-unknown-linux-gnu.tar.gz
# Or use Docker
docker pull ghcr.io/promptexecution/just-mcp:latest
# Or download from GitHub releases
wget https://github.com/promptexecution/just-mcp/releases/latest/download/just-mcp
🔗 Related Projects
- Just - The command runner this integrates with
- Model Context Protocol - The protocol specification
- rmcp - Official Rust MCP SDK
Friends of just-mcp
- just-vscode - VSCode extension with LSP integration for enhanced Just authoring
- just-awesome-agents - Collection of patterns and tools for agent execution with Just# Test change to trigger pre-push hook
Related MCP servers
Dispatch a human verifier to physically verify anything in the real world. For AI agents.

Pushary
The decision layer for AI agents. Your agent asks, a person approves or denies on their phone.

QRSalt
Make, re-point and track QR codes and short links, and read QR images, from your AI assistant.

io.github.QasperAI/qasper
Discover and book businesses via AI agents.

io.github.PromptPartner/bexio-mcp-server
Swiss accounting integration for Bexio with 315 AI tools for invoices, contacts, projects, and payments.
B2B sales intelligence: find companies, extract leads, enrich contacts with emails/phones.
View repository →