Skip to main content
Glama
Sign In
Claude Code MCP Server

Claude Code MCP Server

by sohampatwardhan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Run Claude Code locally

claude_run_local
Destructive

Runs Claude Code headless in an existing local checkout when tasks need the local toolchain or hardware, returning a background job ID to poll for results.

Instructions

Run Claude Code headless on this machine (claude -p) in an existing checkout, instead of a cloud session: for work that needs the local toolchain or hardware. cwd must be inside a CLAUDE_MCP_LOCAL_ROOTS directory after resolving symlinks; with no roots configured every call fails with LOCAL_RUNS_DISABLED. Unless CLAUDE_MCP_LOCAL_ALLOW_SHELL is set, the run uses Claude Code's --restricted mode: no shell or code tools, no WebFetch, no MCP servers, and the checkout's settings, hooks and .mcp.json are not loaded (needs Claude Code 2.1.248 or later). The run is a background job and this call returns within a few seconds: if status is not done, poll claude_get_session with job_id until local_job.status is done or the call returns an error. The final result has the session_id (pass it as resume to continue), the result text, turns, cost and usage, denied tools, and the files git status lists. permission_mode defaults to dontAsk, which denies anything not read-only or in allowed_tools; permission bypass is never used. Pre-approving Bash or using auto mode runs shell commands unasked and fails with LOCAL_SHELL_DISABLED unless CLAUDE_MCP_LOCAL_ALLOW_SHELL is set. claude_cancel_session stops a run.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "cwd": "<cwd>",
      "prompt": "<prompt>"
    },
    "name": "claude_run_local"
  }
}

Input Schema

NameRequiredDescriptionDefault
cwdYesAbsolute directory to run in: an existing checkout inside a CLAUDE_MCP_LOCAL_ROOTS directory. Compared after resolving symlinks.
modelNoModel alias (opus, sonnet, haiku, fable) or full model name. Omit for the CLI's default.
promptYesTask for Claude Code.
resumeNosession_id of an earlier local run to continue (claude --resume). Omit to start a new session.
max_turnsNoStop after this many agentic turns.
timeout_sNoTime limit for the run, in seconds. Omit to use CLAUDE_MCP_TIMEOUT_MS.
allowed_toolsNoBuilt-in tools that run without asking (--allowedTools). Bash allows every shell command and needs CLAUDE_MCP_LOCAL_ALLOW_SHELL.
permission_modeNodontAsk (default): only reads and allowed_tools run; anything that would prompt is denied. acceptEdits: also file edits and common filesystem commands in cwd. plan: read-only exploration. auto: a background classifier reviews each action, including shell commands; needs CLAUDE_MCP_LOCAL_ALLOW_SHELL. Permission bypass is not available.

Output Schema

NameRequiredDescriptionDefault
cliYesexit_code, and the tail of stderr. stdout is empty when the result line was read (it is the session transcript), otherwise its last 4,000 characters.
cwdYesDirectory the CLI ran in, after resolving symlinks.
argsYes
filesYesPaths git status lists after the run, plus paths that were listed before and are clean now. Changes Claude committed don't appear. Null until done, and when cwd is not a git work tree.
usageYes
errorsYesErrors the CLI reported on an error result.
job_idYesBackground job for this run. Pass it to claude_get_session until status is done.
parsedYesTrue when the CLI's final result line was read.
resultYesText of the final assistant message.
statusYesstarting: claude -p is running and has not reported a session yet. running: session_id is known and the CLI has not exited. done: the CLI exited and the result below is final. cancelled: claude_cancel_session stopped the run.
subtypeYesResult subtype, such as success or error_max_turns.
is_errorYesTrue when the run ended in an error state (max turns, an API error, a refusal).
num_turnsYes
elapsed_msYesTime since the run started, or its total duration once done.
rate_limitYesThe latest rate-limit event the run reported, or null if none.
restrictedYesTrue when the run used Claude Code's --restricted mode (CLAUDE_MCP_LOCAL_ALLOW_SHELL off): no shell or code tools, no WebFetch, no MCP servers, and the checkout's settings, hooks and .mcp.json not loaded.
session_idYesLocal session id. Pass it as `resume` to continue this session.
total_cost_usdYes
permission_modeYes
assistant_messagesYesAssistant messages seen so far.
permission_denialsYesTools whose calls were denied, by name.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.3

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations (destructive, open-world, non-idempotent), the description discloses the sandbox roots requirement with symlink resolution, the --restricted mode default and what it disables (shell, WebFetch, MCP servers, repo settings/hooks/.mcp.json), the minimum Claude Code version, and that the call returns quickly as a background job. It also covers the permission model (dontAsk default denies anything not read-only) and that bypass is never available — all information an agent cannot get from the annotations alone.

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?

It is a dense paragraph rather than a structured list, but it is front-loaded with the core purpose and alternative, and nearly every clause adds operational constraint or failure mode. Mild deduction for packing permission, sandbox, asynchronous, and polling behavior into one unbroken block where bullets would scan faster.

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

Completeness5/5

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

For a destructive, open-world local-execution tool with 8 parameters, the description covers the prerequisites, sandbox constraints, permission semantics, async execution model, polling path, and continuation path. It even summarizes the result fields (session_id, result text, turns, cost, denied tools, git status) despite an output schema existing, leaving no material gap for correct invocation.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-call meaning the schema does not: session_id from the final result is what you pass as `resume` to continue, and `job_id` from the return value drives polling. The permission_mode/allowed_tools interplay (Bash pre-approval or auto mode requires CLAUDE_MCP_LOCAL_ALLOW_SHELL) reinforces the enum semantics with a concrete failure mode.

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 first sentence states a specific verb and resource ('Run Claude Code headless on this machine (`claude -p`) in an existing checkout') and explicitly contrasts it with a cloud session, which directly disambiguates it from the sibling claude_create_cloud_session.

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?

It gives a positive selection rule ('for work that needs the local toolchain or hardware'), names the implicit alternative (a cloud session), and specifies the follow-up procedure to poll claude_get_session with job_id, plus claude_cancel_session for stopping. It also states the failure conditions (LOCAL_RUNS_DISABLED, LOCAL_SHELL_DISABLED) that tell an agent when a call cannot succeed.

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

Deploy Server

Other Tools