olivetin-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@olivetin-mcp restart the Nginx server"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
olivetin-mcp
Community-maintained Python implementation. Not affiliated with or endorsed by the OliveTin project.
A hardened MCP server that exposes OliveTin actions as tools, with built-in human-in-the-loop approval for destructive operations.
One-liner (uvx + Claude Code)
claude mcp add olivetin -e OLIVETIN_URL=http://localhost:1337 -- uvx --from git+https://github.com/vaddisrinivas/olivetin-mcp.git olivetin-mcpThe Problem: AI Agents and the Trust Gap
AI agents (Claude, GPT, etc.) are increasingly capable of running shell commands and managing infrastructure. But there's a fundamental trust gap:
Without approval gates, an agent can
rm -rf /, restart production, or leak secrets — and you only find out after the damage is done.Without action discovery, agents guess at commands instead of using your pre-defined, parameterized, tested actions.
Without audit trails, you can't answer "what did the agent do and why?"
Giving an AI agent a raw shell is like giving a new hire root access on day one. You wouldn't do it. Instead, you'd give them a runbook of approved actions and require sign-off for anything destructive. That's exactly what this project does.
OliveTin is the runbook — safe, parameterized shell actions with a web UI. olivetin-mcp is the bridge that lets AI agents use that runbook, with human approval built in.
Related MCP server: Agentrim MCP
Why OliveTin-MCP?
OliveTin lets you define shell commands as safe, parameterized actions with a web UI. olivetin-mcp bridges those actions into the Model Context Protocol so Claude (or any MCP client) can discover and execute them — with automatic human approval gates for anything destructive.
Without this bridge: Claude can't see or trigger your OliveTin actions. You'd need to manually copy-paste commands or build custom integrations.
With this bridge: Claude discovers all your actions automatically, validates arguments, and asks for human approval before running anything dangerous.
Approach | Pros | Cons |
Direct shell via Claude | Simple, no setup | No action discovery, no approval gates, no audit trail |
OliveTin Web UI alone | Built-in approval UI | No AI integration, manual operation only |
OliveTin API directly | Full control | Manual auth, no MCP schema, no standardized discovery |
olivetin-mcp (this) | Auto-discovery, approval chain, hardened container, MCP standard | Requires MCP client + OliveTin |
How It Works
┌──────────────┐ SSE ┌──────────────────┐ REST API ┌──────────────┐
│ MCP Client │ <──────────────> │ olivetin-mcp │ ──────────────────> │ OliveTin │
│ (Claude, etc)│ port 9003 │ (this server) │ port 1337 │ (host) │
└──────────────┘ └──────────────────┘ └──────────────┘
│
v
┌──────────────┐
│ Approval UI │
│ /pending/:tok │
└──────────────┘Discovers OliveTin actions and registers each as an MCP tool
Classifies actions as read-only or destructive based on naming conventions
Gates destructive actions behind a two-step approval chain:
MCP native elicitation (inline dialog in Claude Code / Claude Desktop)
URL-based approval (human visits
/pending/<token>to approve or deny)
Executes approved actions via the OliveTin REST API
Exposes resources for action catalogs, execution logs, and pending approvals
Features
Comprehensive OliveTin API coverage (actions, logs, execution status, kill)
Three authentication modes (reverse-proxy headers, JWT, HTTP Basic)
Built-in static tools:
brave_search,render_diagram,render_chartRate limiting per action
Structured logging with
structlogRetry with exponential backoff via
tenacitySecurity headers on all HTML responses
/healthzhealth check endpoint
Requirements
Python 3.11+
OliveTin running and accessible — Installation guide | GitHub | Discord
Quick Start
One-liner (uvx + Claude Code)
claude mcp add olivetin -e OLIVETIN_URL=http://localhost:1337 -- uvx --from git+https://github.com/vaddisrinivas/olivetin-mcp.git olivetin-mcpThis installs and runs via stdio transport. For SSE (Docker), see below.
Docker (recommended for production)
docker build -t olivetin-mcp .
docker run -d \
-p 9003:9003 \
-e OLIVETIN_URL=http://host.docker.internal:1337 \
olivetin-mcpDocker Compose
A docker-compose.yml is included for running olivetin-mcp alongside OliveTin:
docker compose up -dpip
pip install olivetin-mcp
python -m mainFrom source
git clone https://github.com/vaddisrinivas/olivetin-mcp.git
cd olivetin-mcp
pip install -e ".[test]"
python main.py # stdio (for claude mcp add)
python main.py --sse # SSE server on port 9003 (for Docker)MCP Client Configuration
Claude Code (recommended)
# Via uvx (no install needed):
claude mcp add olivetin -e OLIVETIN_URL=http://localhost:1337 -- uvx --from git+https://github.com/vaddisrinivas/olivetin-mcp.git olivetin-mcp
# Or if installed locally:
claude mcp add olivetin -- olivetin-mcpClaude Desktop
For SSE mode (Docker), add to your claude_desktop_config.json:
{
"mcpServers": {
"olivetin": {
"url": "http://localhost:9003/sse"
}
}
}Claude Code (SSE)
claude mcp add olivetin --transport sse http://localhost:9003/sseConfiguration
All configuration is via environment variables. Copy .env.example to .env to get started.
Variable | Default | Description |
|
| MCP SSE server port |
|
| OliveTin API URL |
|
| Seconds to wait for approval decision |
|
| Public URL for approval links (e.g. |
|
| MCP elicitation dialog timeout |
|
| Docker secrets mount path |
|
| Action catalog refresh interval |
Authentication
Pick one mode depending on your OliveTin setup:
Reverse-proxy headers (e.g. Authelia, Authentik):
OLIVETIN_REMOTE_USER=serviceaccount
OLIVETIN_REMOTE_GROUPS=admins,operators
OLIVETIN_USER_HEADER=X-Remote-User # optional, default shown
OLIVETIN_GROUPS_HEADER=X-Remote-Groups # optional, default shownJWT bearer token:
OLIVETIN_JWT_TOKEN=eyJhbGci...
# or mount as /run/secrets/olivetin_jwt_tokenHTTP Basic auth:
OLIVETIN_BASIC_USER=admin
OLIVETIN_BASIC_PASS=changemeSecurity
This project is designed to be run as a hardened container:
Non-root user (
bridge:10001) with no login shellStripped attack surface: all shells, network tools, and compilers removed
No runtime pip: package manager removed after build
Read-only filesystem: designed for
read_only: truein Docker ComposeDropped capabilities: all Linux capabilities can be dropped
Human-in-the-loop: destructive actions require explicit approval
XSS protection: Jinja2
autoescape=Trueon all templatesCryptographic tokens: approval tokens via
secrets.token_urlsafe(16)Security headers:
X-Frame-Options,CSP,X-Content-Type-Optionson all HTML responsesSSRF protection: diagram specs checked for disallowed URI schemes
See SECURITY.md for vulnerability reporting and threat model.
MCP Tools
Dynamic (one per OliveTin action)
Each OliveTin action is registered as an MCP tool. Read-only actions (prefixed with [read-only] or ro_ binding ID) execute immediately. All others go through the approval chain.
Static
Tool | Description |
| List all actions with schemas and approval status |
| Recent execution history |
| Status of a running execution |
| Kill a running execution |
| Force refresh the action catalog |
| Show pending approval queue |
| Web search via Brave Search API |
| Render Mermaid/PlantUML/D2 diagrams |
| Render charts via QuickChart |
MCP Resources
URI | Description |
| Full action catalog (JSON) |
| Detailed action documentation |
| Recent execution history |
| Action-specific logs |
| Pending approval queue |
Example OliveTin Actions
Here's how OliveTin actions map to MCP tools:
# In your OliveTin config.yaml
actions:
# This action executes immediately (no approval) because of [read-only] prefix
- title: "[read-only] Get Service Status"
shell: docker ps --format 'table {{.Names}}\t{{.Status}}'
# This action requires human approval before execution
- title: Deploy Service
shell: cd /srv/{{ service }} && docker compose pull && docker compose up -d
arguments:
- name: service
type: ascii_identifier
choices:
- value: api
- value: web
- value: workerFAQ / Troubleshooting
Q: Claude shows the action but gets "Could not reach OliveTin"
Verify OliveTin is running:
curl http://your-olivetin:1337/api/GetDashboard -X POST -d '{}'If using Docker, ensure network connectivity (use
http://host.docker.internal:1337on Docker Desktop, or the container network name in Docker Compose)Check
OLIVETIN_URLenv var
Q: Actions require approval but I want some to be read-only
Prefix the action title with [read-only] or the binding ID with ro_ in your OliveTin config. The bridge automatically classifies these as safe.
Q: Approval links don't work / show "Not Found"
Set APPROVAL_BASE_URL to the publicly reachable URL of the bridge (e.g. http://192.168.1.10:9003). The default localhost only works when the browser is on the same machine.
Q: MCP client times out waiting for approval
The default approval timeout is 120 seconds. Increase APPROVAL_TIMEOUT_SECS if needed. The elicitation dialog (inline in Claude) times out after 30 seconds (ELICITATION_TIMEOUT_SECS) before falling back to URL-based approval.
Q: Actions aren't showing up in Claude
Check the bridge logs for
actions_loaded— it should show the countRun the
reload_actionstool to force a refreshVerify OliveTin has actions configured and they aren't marked
hidden: true
Q: How do I use Brave Search?
Mount the API key as a Docker secret at /run/secrets/brave_api_key, or set BRAVE_API_KEY in your environment. Get a key at brave.com/search/api.
Risks and Limitations
Single maintainer: Bus factor of 1. See GOVERNANCE.md for co-maintainer path.
No end-to-end encryption: Communication between this bridge and OliveTin is HTTP by default. Use HTTPS in production or keep them on the same host/network.
Approval UI is basic: The URL-based approval page has no authentication beyond the cryptographic token. Anyone with the link can approve/deny. Keep approval URLs private.
Not a security boundary: This bridge adds an approval layer, but it trusts OliveTin's API. If OliveTin is compromised, the bridge can't protect you.
Young project: This is v0.1.0. Expect rough edges. File issues.
Related Projects
OliveTin — The automation platform this bridge connects to. Written in Go by James Read. Docs | Discord
Model Context Protocol — The open standard for AI tool integration. Spec | GitHub
FastMCP — The Python MCP framework this server is built on.
OpenClaw — Another approach to AI agent orchestration (different architecture).
Background
The motivation: routing AI agents through OliveTin's pre-defined, parameterized actions is fundamentally safer than giving agents raw shell access. The approval chain ensures a human is always in the loop for anything destructive.
Development
# Install all extras
make install
# Run all CI checks locally
make ci
# Or individually:
make test # pytest with coverage
make lint # ruff check
make type # mypy
make format # auto-formatSee CONTRIBUTING.md for more details, and ARCHITECTURE.md for codebase overview.
License
Available Tools
18 toolsbrave_searchARead-only
Search the web using the Brave Search API. Returns top results with title, URL, and description. No approval needed — read-only.
Inputs: query (required), count. Returns: result
get_action_bindingARead-only
Fetch a single OliveTin action binding by ID (GetActionBinding RPC). Returns full Action proto including arguments, icon, timeout, and ACL fields. No approval needed — read-only.
Inputs: binding_id (required). Returns: result
get_entitiesARead-only
List all OliveTin entities (GetEntities RPC). Entities represent monitored services/hosts. No approval needed — read-only.
Inputs: no named parameters. Returns: result
get_entityARead-only
Fetch a single OliveTin entity by unique key and type (GetEntity RPC). No approval needed — read-only.
Inputs: unique_key (required), type. Returns: result
get_execution_logsARead-only
Get recent OliveTin execution history (LogEntry records). Proto fields: datetime_started, action_title, output, exit_code, timed_out, user, execution_tracking_id, blocked. No approval needed.
Inputs: action_id, page_size. Returns: result
get_execution_statusARead-only
Check the status of a running OliveTin action by its execution_tracking_id (returned by StartAction). No approval needed.
Inputs: execution_tracking_id (required). Returns: result
get_server_infoARead-only
Return OliveTin server info and version (Init RPC). No approval needed — read-only.
Inputs: no named parameters. Returns: result
kill_actionARead-only
Kill a currently running OliveTin action by its execution_tracking_id. Only works when the LogEntry's can_kill field is true. Returns killed/already_completed/not_found status. No approval needed — this is a safety stop, not a destructive write.
Inputs: execution_tracking_id (required). Returns: result
list_olivetin_actionsARead-only
List all available OliveTin actions: IDs, titles, argument schemas, and whether each requires approval. No approval needed.
Inputs: no named parameters. Returns: result
list_pending_approvalsARead-only
List all OliveTin actions currently waiting for human approval, with the URL the human must visit to approve or deny. Call this after triggering a destructive action to get the approval link. No approval needed — read-only.
Inputs: no named parameters. Returns: result
readyzARead-only
OliveTin readiness probe (GetReadyz RPC). Returns 200/ready when OliveTin is healthy. No approval needed — read-only.
Inputs: no named parameters. Returns: result
reload_actionsARead-only
Force an immediate refresh of the OliveTin action catalog from GetDashboard. Use this after adding, removing, or editing actions in OliveTin config without waiting for the automatic refresh interval. No approval needed — read-only.
Inputs: no named parameters. Returns: result
render_chartARead-only
Render a Chart.js config as PNG via quickchart.io. Returns /tmp path. No approval needed.
Inputs: config (required), width, height, background_color. Returns: result
render_diagramARead-only
Render a Mermaid diagram spec as PNG via mermaid.ink. Returns /tmp path. No approval needed.
Inputs: spec (required). Returns: result
restart_actionADestructive
Restart a previously executed OliveTin action by its execution_tracking_id (RestartAction RPC). Re-runs with the same arguments as the original execution. Requires human approval — this re-triggers a real action on the host.
Inputs: execution_tracking_id (required). Returns: result
start_action_asyncADestructive
Start an OliveTin action asynchronously (StartAction RPC). Returns an execution_tracking_id immediately without waiting for completion. Use get_execution_status to poll progress, kill_action to cancel. Requires human approval — this triggers a real action on the host.
Inputs: action_id (required), arguments. Returns: result
validate_argumentARead-only
Validate an argument value against an OliveTin argument type (ValidateArgumentType RPC). type: unicode | ascii_identifier | url | int | float | bool. No approval needed — read-only.
Inputs: type (required), value (required), binding_id, argument_name. Returns: result
whoamiARead-only
Return information about the current authenticated OliveTin user (WhoAmI RPC). No approval needed — read-only.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
The core OliveTin tools are mostly distinct, but the inclusion of unrelated tools (brave_search, render_diagram, render_chart) creates confusion about the server's purpose and could lead to misselection. There is also mild overlap between get_execution_logs and get_execution_status, though descriptions help clarify.
Most tools follow a clear verb_noun snake_case pattern (e.g., list_olivetin_actions, get_execution_status, kill_action). Minor exceptions like whoami, readyz, and brave_search deviate from the pattern but are still recognizable and don't cause significant inconsistency.
At 18 tools, the set is on the heavier side. The 15 OliveTin-specific tools are reasonably scoped for the domain, but the three unrelated utility tools pad the count and make the server feel less focused.
The OliveTin surface covers the core lifecycle: listing/getting actions, starting/killing/restarting, status/logs, approvals, entities, validation, user/server info, health, and reload. Minor gaps include lack of entity mutations and synchronous action start, but these are not critical for typical workflows.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
The MCP server that vets MCP servers: identity, risk grade and per-tool risk before you install.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Related MCP Servers
AlicenseAqualityBmaintenanceA hardened, self-hosted MCP server that lets AI agents query and govern an Infraveil control plane in-loop, reading state and filing deploy/remediation requests that require human approval.7AGPL 3.0- AlicenseNot gradedqualityDmaintenanceA least-privilege enforcement proxy for MCP servers. It sits between MCP clients and upstream servers, enforcing tool policies, hiding denied tools, requiring human approval for risky actions, and providing a structured audit trail.MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that provides a security gateway for AI agents, enforcing allow/confirm/deny policies on tool calls and requiring human approval for risky operations, with full audit logging.-
- AlicenseNot gradedqualityCmaintenanceAn MCP server exposing scoped, read-only enterprise operations tools with fail-closed credential handling. It returns opaque approval IDs for mutations and requires a separate operator approval command to release one-time capabilities.MIT