Purpose
just-mcp is an MCP (Model Context Protocol) server for the Just command runner. It enables AI assistants to discover, execute, and introspect recipes in a Justfile through the standardized MCP protocol. Its core purpose is to provide LLMs with a safer and more context-efficient command execution abstraction than direct bash access.
Main Capabilities
- Full MCP server: integrates rmcp 0.3.0, compatible with the MCP 2024-11-05 protocol.
- Recipe discovery: parses and lists all available recipes in a Justfile.
- Recipe execution: executes recipes, supports arguments, and captures structured output.
- Recipe introspection: retrieves detailed information, parameters, and documentation for recipes.
- Justfile validation: performs syntax and semantic validation and reports errors.
- Environment management: supports .env files and variable expansion.
- Test coverage: 33 integration and unit tests pass.
MCP Tools
- list_recipes: lists all available recipes in the justfile.
- run_recipe: executes the specified recipe, with optional arguments.
- get_recipe_info: retrieves detailed information about the specified recipe.
- validate_justfile: validates syntax and semantic errors in the justfile.
Usage
Installation methods include pkgx, Docker images, and Claude Desktop integration (requires adding just-mcp to Claude Desktop's MCP configuration). pkgx downloads the tarball for the corresponding platform, extracts the executable to ${PKGX_DIR:-$HOME/.pkgx}/bin, and runs the CLI with the passed arguments; for long-term use, this bin directory needs to be added to the shell's PATH. Docker image tags include latest, X.Y.Z, X.Y, X.
Use Cases
just-mcp is suitable for users doing agent execution. Its advantages include:
- Extremely low overhead, possibly better than other similar tools.
- Human-friendly, justfile is easy for humans to read, and also low overhead for LLMs.
- Fast and simple, suitable for scenarios that prefer lightweight solutions.
- Friendly to small models, suitable for self-hosted GPU/CPU open-source models, and applicable to 8k-32k context limits.
Just supports introducing the following safety modes: transparent logging without interfering with the agent; using a small model to scan for "whether it is harmful" before command execution; a command validation mode similar to Python decorators; idempotent execution based on a git repository.
Current Status and Limitations
The project is currently about 67% complete (8/12 core tasks). Implemented features include a full MCP server, recipe discovery, recipe execution, recipe introspection, Justfile validation, environment management, and full test coverage. Remaining tasks include: an LSP-style completion system, enhanced diagnostics, a virtual file system (supporting stdin, remote sources, and in-memory buffers), and release preparation (documentation, CI/CD, crate publishing). Future enhancement directions include: a plugin system for custom recipe types, integration with other build tools, performance optimization for large justfiles, and advanced dependency visualization.
The tech stack uses Rust 1.82+ (async/await), rmcp 0.3.0, serde/serde_json, snafu, and tokio. The project uses the MIT license. Related projects include Just, the MCP protocol, rmcp, as well as just-vscode, just-awesome-agents, and others.
