binnacle-mcp

# binnacle Binnacle is a small MCP server that lets an AI agent work on a Linux/Raspberry Pi through deterministic tools: read/search files, run commands, and manage long-running jobs. > **Status:** developer-oriented Linux proof of concept. Distribution > releases are versioned and verified independently of Raspberry Pi > deployments. Check the package index for PyPI availability. **Security:** Binnacle allows AI clients to read/write files and run shell commands within configured roots. The bearer token is sensitive; client identifiers used for tool visibility are not a strong authorization boundary. Use it only on a trusted machine/network, keep the endpoint bound to localhost, and put an authenticated gateway in front of any tunnel. **Do not expose the MCP endpoint to the public Internet without appropriate security controls.** ## Install from PyPI Binnacle targets Linux with Python 3.10–3.14. Its managed services use systemd --user and additionally require bash and ripgrep (rg). ```bash python -m pip install binnacle-mcp==1.0.1 binnacle --help binnacle doctor ``` Review any host changes before running setup: ```bash binnacle setup --dry-run ``` For managed services, configuration, bearer token provisioning and the optional tunnel companion, follow the Quick start and configuration guidance below. Installation does **not** automatically start or expose an MCP server. ## Quick start Requirements: Linux with systemd user services, bash, ripgrep (rg), Git, and uv. Python 3.10-3.14 is supported by the current test matrix. ```bash git clone https://github.com/grammy-jiang/binnacle.git cd binnacle # Create/sync the development environment, install every configured Git hook, # and verify the checkout. uv run scripts/dev.py bootstrap # Preview the machine changes first: every action, and the unit diff. uv run binnacle setup --dev "$PWD" --dry-run # Create the bearer token plus the MCP and durable-jobs systemd user units. # The MCP checkout auto-reloads i…