Skip to main content
Glama
local-exec

local-exec

README.md
# mcp-local-exec

A lightweight **Model Context Protocol (MCP)** server that delegates shell/terminal tasks from a cloud reasoning agent (Antigravity, Claude Desktop, Claude Code, Cursor, etc.) to a **local LLM running on Ollama**.

Instead of flooding your main agent's context window with raw `ls`, `grep`, `git diff`, or log outputs, `local-exec` runs a fast local sub-agent that executes up to 4 shell steps and returns only the clean, extracted data—drastically cutting token usage.

## Hybrid Architecture (Recommended: Graphify + `local-exec`)

`mcp-local-exec` works standalone, but it shines in a **hybrid cloud-local setup** paired with [Graphify](https://github.com/Graphify-Labs/graphify.git) (or any codebase indexing MCP):

1. **Main Agent (Cloud):** Handles high-level reasoning and planning.
2. **Graphify (MCP):** Maps the codebase structure and locates relevant files without reading everything.
3. **`local-exec` (MCP + Ollama):** Acts as the local "hands", running shell commands and returning concise extracted outputs.
> **Zero-Token Graphify Setup:** Want to initialize Graphify, link your Markdown docs into `graph.json` at 0 token cost, or convert PDFs to Markdown for your agents? Check out my companion toolkit: [**`llm-workflow-utils`**](https://github.com/AdvisingDesert/llm-workflow-utils).

## Prerequisites

- **Node.js** v18+
- **Ollama** installed and running ([ollama.com](https://ollama.com))

### Recommended Local Models

Pick one model based on your available RAM/VRAM:

| Model (Ollama Tag) | Size | Recommended RAM | Best For |
| :--- | :--- | :--- | :--- |
| **`lfm3:1.7b`** | ~1.2 GB | 8–16 GB | Maximum speed and minimal battery impact (`ls`, `git status`, simple lookups). |
| **`qwen3.5:4b`** *(Default)* | ~2.5 GB | 16 GB | Best balance: reliable with chained bash commands, pipes, `grep`, and strict JSON output. |
| **`qwen3.5:9b`** | ~5.5 GB | 16–32 GB | Maximum accuracy on long logs and complex shell pipelines. |

Pull your chosen model:
```bash
ollama pull qwen3.5:4b
```

## Installation

```bash
git clone https://github.com/AdvisingDesert/mcp-local-exec.git
cd mcp-local-exec
npm install
```
Quick check (it should stay idle waiting on stdio; press Ctrl+C to exit):

```bash
node index.js
```

## Configuration

Find your absolute Node path first (GUI apps on macOS often don't inherit your shell PATH):

```bash
which node
```

### Antigravity / Claude Desktop / Generic MCP Clients

Add local-exec to your mcpServers config:

```json
{
  "mcpServers": {
    "local-exec": {
      "command": "/path/to/node",
      "args": ["/path/to/mcp-local-exec/index.js"],
      "env": {
        "OLLAMA_MODEL": "qwen3.5:4b",
        "OLLAMA_URL": "http://localhost:11434/api/chat"
      }
    }
  }
}
```

(The env block is optional—qwen3.5:4b and http://localhost:11434/api/chat are the defaults.)

### Claude Code (CLI)

```bash
claude mcp add local-exec -- /path/to/node /path/to/mcp-local-exec/index.js
```

## Agent Rules (Prompting)

To make your main agent delegate automatically, add the rule template from [`examples/local-exec-rule.md`](examples/local-exec-rule.md) to your `.agents/rules/`, `CLAUDE.md`, or project instructions.

## Safety & Guardrails
local-exec executes shell commands generated by a local LLM. It includes:

- A code-level regex guardrail that blocks destructive/privileged patterns (rm -rf, sudo, git reset --hard, git clean -f, dd, mkfs, etc.).

- Strict 15s command timeout, 4-step execution cap, and 2-error circuit breaker.

> **Disclaimer:** Always run this tool inside trusted development directories and maintain backups/git commits. Regex guardrails reduce risk but cannot guarantee 100% sandboxing.

## License 

MIT