Skip to main content
Glama
local-exec

local-exec

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.

mcp-local-exec works standalone, but it shines in a hybrid cloud-local setup paired with Graphify (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.

Related MCP server: token-ninja

Prerequisites

  • Node.js v18+

  • Ollama installed and running (ollama.com)

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:

ollama pull qwen3.5:4b

Installation

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):

node index.js

Configuration

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

which node

Antigravity / Claude Desktop / Generic MCP Clients

Add local-exec to your mcpServers config:

{
  "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)

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 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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers