Skip to main content
Glama
rasvan-ghiliciu

local-executor-mcp

by rasvan-ghiliciu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

local-executor-mcp

An MCP server that lets a frontier planner (Claude Code) delegate mechanical code-generation subtasks to a local LLM served by llama-swap, to save frontier-model tokens.

Mental model: Claude Code plans and verifies; the local model does the high-volume, mechanical writing. The split saves tokens because the expensive part — generating large amounts of output — happens on a free local model.

Design choices (and why)

  • Generation-only, stateless. The server never writes files and never runs tests. Claude Code keeps its native file + bash tools for that. This keeps the server portable (no repo coupling, no Windows path pain) and trivial to share.

  • Compact output. The tool returns just the generated artifact plus a short usage footer. (Claude Code warns when an MCP tool output exceeds ~10k tokens, and re-reading huge blobs would eat the token savings.)

  • Model routing built in. A tier argument routes between a quality model and a fast model.

  • Fallback is explicit. On failure the tool returns DELEGATION_FAILED and tells the planner to do the task itself — so a weak local result never blocks you. This is your guardrail against compounding errors.

  • Metrics. Every call is appended to ~/.local-executor-mcp/usage.jsonl (model, tokens, latency, ok/fail) so you can quantify savings later.

Related MCP server: mcp-local-llm

Model recommendations (from a typical llama-swap list)

Use

Model

Why

quality (default)

qwen3.6-35b-a3b-q8_0

35B MoE, ~3B active → fast and capable, high-fidelity quant

fast

qwen3.5-4b-q8_0

small, quick, for trivial / high-volume tasks

A/B alternative for quality

qwopus3.6-35b-a3b-v1-q8_0

if code-tuned, may beat Qwen — measure it

Avoid for code: translation models (hy-mt2-*, tower-plus), the vision model (minicpm-v), and ultra-low quants (iq2_xxs / iq3_xxs).

Build

Requires Node.js 18+.

npm install
npm run build

Quick test (no Claude Code needed)

Confirm the server starts and your backend is reachable:

LOCAL_LLM_BASE_URL=http://10.0.0.42:8080/v1 npx @modelcontextprotocol/inspector node build/index.js

In the Inspector UI, call list_local_models first, then try delegate_code.

Use it from Claude Code

Solo (personal)

claude mcp add local-executor \
  --env LOCAL_LLM_BASE_URL=http://10.0.0.42:8080/v1 \
  --env LOCAL_LLM_MODEL_QUALITY=qwen3.6-35b-a3b-q8_0 \
  --env LOCAL_LLM_MODEL_FAST=qwen3.5-4b-q8_0 \
  -- node /absolute/path/to/local-executor-mcp/build/index.js

Restart your Claude Code session so the tools are discovered.

Team rollout (the point of this project)

Use project scope so the config is checked into git and every teammate gets it automatically. Copy .mcp.json.example to .mcp.json at the repo root and commit it. The first time each teammate opens the repo, Claude Code asks them to approve the server (workspace trust), then it just works.

  • .mcp.json.example — assumes the package is published to npm and runs via npx. Lowest friction; teammates need nothing installed.

  • .mcp.json.vendored.example — no publishing: drop the built server in tools/local-executor-mcp/ inside the repo and point node at it.

The backend URL uses ${LOCAL_LLM_BASE_URL:-...default...} expansion, so each machine can override it via an environment variable without editing the file.

Windows notes

  • Node + npx work fine on Windows for stdio servers like this one.

  • If a teammate hits issues with npx, pre-install once (npm i -g @yourorg/local-executor-mcp) and set "command": "local-executor-mcp".

  • Nothing here touches the filesystem, so there are no path-separator issues.

How to actually drive it (prompt Claude Code like this)

"Plan the module. For the boilerplate parts — the Odoo model fields, the XML views, and the security CSV — use the delegate_code tool with a precise spec and the relevant context, then review what comes back and run the tests."

Good delegation targets: boilerplate, scaffolding, CRUD, test stubs, format conversions, Odoo models/views/manifest/ir.model.access.csv, bulk rule-based edits. Keep logic, debugging, and security-sensitive code on Claude.

Inspect your savings

cat ~/.local-executor-mcp/usage.jsonl

Each line records the model, token counts, latency and success. Aggregate it to get "X tokens / Y% of a representative workload handled locally at Z% fallback rate" — a quantified, defensible impact claim.

Available Tools

2 tools
delegate_codeA

Delegate a self-contained, mechanical code-generation subtask to a local LLM to save frontier-model tokens. GOOD for: boilerplate, scaffolding, repetitive CRUD, test stubs, format/data transformations, bulk edits with a clear rule, Odoo models/views/manifests. NOT for: subtle logic, debugging, cross-file reasoning, or security-sensitive code (do those yourself). Provide a precise spec plus any context the worker needs; it returns ONLY the generated artifact. You, the planner, verify and integrate it.

ParametersJSON Schema
NameRequiredDescriptionDefault
taskYesPrecise specification of what to generate. Be explicit — the worker will not infer your intent.
tierNo'quality' (default) uses the larger model; 'fast' uses a small model for trivial / high-volume tasks.
contextNoRelevant existing code, conventions, type/interface definitions, or specs the worker must follow.
languageNoTarget language or format, e.g. 'typescript', 'python', 'odoo-xml-view'.

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden of behavioral disclosure. It states that the tool 'returns ONLY the generated artifact' and that the planner must 'verify and integrate it,' which are key behavioral traits. However, it does not disclose potential failure modes, error handling, or any side effects, leaving some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear purpose statement, a 'GOOD for' list, a 'NOT for' list, and an instruction. It is somewhat longer than the ideal two-sentence example, but every section earns its place by adding practical guidance on usage. It is not verbose or redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has four parameters, no output schema, and no annotations. The description covers the essential context: what it does, when to use it, what inputs to provide, and what output to expect (only the artifact). Minor gaps like error handling are not critical for a delegation tool, making this fairly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides descriptions for all four parameters (100% coverage), so the baseline is 3. The description adds general guidance ('Provide a precise spec plus any context the worker needs'), but this is only a slight reinforcement of the task and context parameters without introducing new semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Delegate a self-contained, mechanical code-generation subtask to a local LLM.' It also provides specific examples of good use cases (boilerplate, scaffolding, CRUD) and exclusions, distinguishing it from the sibling tool 'list_local_models' which is about listing models, not delegating code generation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly lists 'GOOD for' and 'NOT for' scenarios, giving clear when-to-use and when-not-to-use guidance. It even instructs the agent to 'do those yourself' for unsuited tasks, which is a direct exclusion. This is exemplary usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_local_modelsA

List the model IDs currently available on the local llama-swap endpoint. Use it to pick a model or to confirm the backend is reachable.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full transparency burden. It mentions the local endpoint and that results reflect availability, but it does not explain error behavior, return format, or what happens if the backend is unreachable. Still, it adds useful context about confirming reachability.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action, and every word adds value. There is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, no-output-schema tool, the description is reasonably complete. It states what the tool returns ('model IDs'), the context ('local llama-swap endpoint'), and practical use cases. It could mention edge cases like empty results or connection errors, but these are minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. The description adds no param details, but none are needed since the schema is empty. It correctly communicates that the tool requires no inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and explicitly identifies the resource ('model IDs available on the local llama-swap endpoint'). It clearly distinguishes itself from the sibling tool 'delegate_code' by focusing on model enumeration rather than code execution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit use cases: 'pick a model' and 'confirm the backend is reachable.' While it does not mention when not to use it or alternatives, for a simple list operation this is adequate guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 2 tool updatesv1.0.0
    • First observeddelegate_code
    • First observedlist_local_models
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have completely distinct purposes: delegate_code handles code generation subtasks, while list_local_models checks available models. There is zero overlap or ambiguity.

Naming Consistency5/5

Both tool names follow a clean verb_noun pattern (delegate_code, list_local_models), using snake_case consistently. The naming is predictable and easy to understand.

Tool Count3/5

With only 2 tools, the server feels minimal. However, the narrow scope of 'local execution' justifies a small surface; it is borderline but not excessive.

Completeness4/5

For its stated purpose, the server covers the core delegation flow and model discovery. A status or cancel tool would be a minor enhancement, but no critical gaps exist.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • codex-dobby-mcp

    Averyy
    A
    license
    A
    quality
    C
    maintenance
    A local MCP server that lets Claude delegate scoped work to Codex with structured results and guardrails, supporting planning, code review, build, reverse engineering, and long-running background tasks.
    11
    MIT

  • mcp-llm-offload

    seaosinc
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that offloads light LLM work from Claude to a model you control, such as a local LLM or any OpenAI-compatible provider, saving frontier-model quota on non-critical tasks.
    MIT