Ninja MCP

Ninja MCP is a set of MCP servers and a small command-line orchestrator for coding, research, and codebase analysis. The current package and release are 1.1.0.

What It Includes

• Coder: simple tasks plus sequential and parallel execution plans.
• Researcher: web search, deep research, source aggregation, and fact checks.
• Secretary: codebase reports, file analysis, search, and git-aware context.
• Agent: a CLI orchestrator for plan, analyze, delegate, review, and run.
• Config TUI: Nord-themed setup, model selection, host-auth detection, and IDE registration.
• Background execution: long tools run as standard MCP Tasks — start a run, get a task id, keep working, fetch or cancel the result later.

TUI Preview

The configuration app uses a Nord palette, a block-letter NINJA logo, keyboard navigation that works on RU and Latin layouts, and lazy model autocomplete.

The Docker installer asks for workspace, profiles, ports, build/start, and credentials in the same style. This preview is generated from the current installer flow; it is not a live container session.

Requirements

• Python 3.11 or newer for a native install.
• Docker Engine with Compose v2 for Docker mode.
• An authenticated host CLI or provider credentials for the operator you use.

Quick Start

Make quickstart

From a checkout, make help lists the available wrappers. Normal users should run make install and choose Native installation or Docker container (isolated) in the first TUI question. Do not run make docker-up before that configuration exists; Docker targets use the TUI-generated ~/.config/ninja-mcp/docker/.env.

The Make targets are thin wrappers around install.sh, uv, and Docker Compose. IMAGE, PROFILE, COMPOSE_PROJECT_NAME, and CONFIG_DIR can be overridden as Make variables. make docker-clean is explicit and removes Compose volumes.

Native TUI

The bootstrap installer opens the setup flow. It can install the package and then configure the native runtime:

curl -fsSL https://raw.githubusercontent.com/angkira/ninja-cli-mcp/main/install.sh | bash

For an existing checkout or an already installed package:

ninja-mcp config install
# Equivalent entry point:
ninja-config install

The main TUI is also available with ninja-mcp config or ninja-config configure. Non-secret settings are written to ~/.ninja-mcp.env; API keys are kept in an AES-256-GCM encrypted store with the OS keychain as the primary backend — never in .env or the environment. See docs/SECRETS.md.

Deployment target

Use Docker when host isolation is more important than host CLI integration:

Run ./install.sh and select Native installation or Docker container (isolated) as the first TUI question. Docker then asks for workspace, profiles, unique localhost ports, build/start, and credentials.

The interactive TUI flow asks for an absolute workspace path (missing directories are created automatically), one or more Compose profiles, unique localhost ports, whether to build and start, and whether to pass API credentials. The headless backend instead requires an existing absolute workspace directory. It creates a project under ~/.config/ninja-mcp/docker and installs the ninja-mcp-docker wrapper in ~/.local/bin.

For internal automation only, the hidden backend accepts environment overrides:

NINJA_DOCKER_WORKSPACE="$PWD" \
NINJA_DOCKER_PROFILES=coder,agent \
NINJA_DOCKER_CODER_PORT=18100 \
NINJA_DOCKER_AGENT_PORT=18103 \
NINJA_DOCKER_NONINTERACTIVE=1 ./install.sh

The wrapper supports start, stop, status, logs, and config:

ninja-mcp-docker start
ninja-mcp-docker status
ninja-mcp-docker logs
ninja-mcp-docker stop

See Docker Quickstart for profiles, volumes, runtime secrets, and troubleshooting.

Unified CLI

Run ninja-mcp <command> --help for command-specific options.

The standalone server entry points remain available: ninja-coder, ninja-researcher, ninja-secretary, and ninja-agent.

Agent CLI

The agent CLI emits readable output by default and JSON with --json:

ninja-mcp agent plan --task "Add email validation" --repo-root .
ninja-mcp agent analyze --repo-root . --focus auth
ninja-mcp agent delegate --to coder --subtask "Implement the validator" --repo-root . --model-class smart
ninja-mcp agent review --repo-root . --files src/auth.py tests/test_auth.py
ninja-mcp agent run --task "Implement and review email validation" --repo-root .

run composes plan, delegate, and review. delegate --to accepts coder, researcher, or secretary; coder model tiers are smart, balanced, and fast.

Coder Routing and Safety

Task type is part of the execution policy:

Parallel complexity is explicit: simple is suitable for independent small work, while complex uses the heavier plan/worktree path. Long-running work is protected by an inactivity-first watchdog, not only a wall-clock deadline. Defaults are 90 seconds for quick tasks and 180 seconds for sequential and parallel tasks. Override with NINJA_INACTIVITY_TIMEOUT, or the per-type NINJA_INACTIVITY_TIMEOUT_QUICK, ..._SEQUENTIAL, and ..._PARALLEL variables.

See Automatic Safety for recovery, worktree controls, and legacy paths that intentionally remain in place.

Provider Authentication

Ninja does not require a new API key when the selected coding CLI is already authenticated on the host. Supported operators: opencode, aider, claude, codex, agy (Antigravity), and junie.

• claude uses the host Claude Code session (sonnet/opus/haiku aliases).
• codex uses the ChatGPT login from the Codex CLI.
• agy (Antigravity) runs locally with its own auth; models are listed live with agy models.
• junie uses JetBrains Account authentication and the junie binary.
• opencode uses its own provider configuration and authentication, and exposes a dynamic provider sub-selection (Anthropic, OpenAI, Google, Z.AI, OpenRouter, …).

Junie uses a flat model id and runs commands shaped like:

junie --model deepseek-v4-flash --output-format text -p . \
  --skip-update-check --task "Review the authentication flow"

The TUI detects Junie and offers its static host-auth model list without a network probe. API-backed operators such as Aider still need the credentials required by that operator. Docker intentionally does not copy host $HOME, host CLI credentials, or docker.sock; use runtime API variables or a protected runtime env file instead.

MCP Host Setup

Detect supported hosts and install their configuration with the unified CLI:

ninja-mcp init detect
ninja-mcp init claude-code --direct
ninja-mcp init codex
ninja-mcp init generic

Use --dry-run to preview a supported config change. See Editor Integrations and Installation Modes.

Documentation

• Docker Quickstart
• Background execution (MCP Tasks)
• Automatic Safety
• CLI Strategies and operators
• Model selection
• TUI installer notes
• Configuration
• MCP architecture
• Coder architecture
• Researcher
• Secretary
• Changelog
• Security
• Contributing

Development

uv sync --all-extras
uv run pytest tests/ -q
uv run ruff check src
uv run mypy src

Ninja MCP is released under the MIT License.