Skip to main content
Glama
LukeLamb

claude-terminal-mcp

by LukeLamb

Terminal — Linux用Claude Desktop拡張機能

Claude Desktop用の拡張機能で、ローカルのLinuxマシン上のターミナル、ファイルシステム、バックグラウンドジョブへのアクセス権をClaudeに付与します。

Linux版Claude Desktopではclaude_desktop_config.json形式のMCPサーバーが読み込まれない(この仕組みはmacOS/Windows専用です)という問題を解決します。Linuxでは、ツールを追加する唯一の方法はインストール可能な拡張機能を経由することです。


⚠️ セキュリティ — 最初に必ずお読みください

この拡張機能をインストールすると、ユーザーアカウントに対してClaudeに無制限のシェルアクセス権が与えられます。 ターミナルからユーザーが実行できることはすべて、Claudeもこのツールを通じて実行可能です。ユーザーが読み取れるあらゆるファイルの読み取り、変更可能なあらゆるものの変更、ソフトウェアのインストール、ネットワーク接続の開始などが含まれます。

このインストールは、誰かに自分のマシンへのSSHセッションを許可するのと同じことだと考えてください。Claudeに見られたくない機密データがあるマシンや、共有システムにはインストールしないでください。

明らかに破壊的なワンライナー(rm -rf /、rm -rf ~、フォーク爆弾、生のディスクデバイスに対するdd/mkfs、shutdown/reboot)を拒否する最小限の組み込み安全拒否リストが存在します。これは最後の手段としての安全策であり、サンドボックスではありません。 悪意のあるコマンドであれば、簡単に回避可能です。これは、一瞬の不注意でホームディレクトリが消去されるのを防ぐために存在します。

制限を強化するには、server.jsの先頭にあるDENYLIST配列を編集して再ビルドしてください。完全に削除するには、DENYLIST = []に設定して再ビルドしてください。


Related MCP server: claude-linux-mcp

機能

Claudeに対して8つのツールを公開します:

ツール

目的

run_command(command, cwd?, timeout?, env?)

bash -lc経由でシェルコマンドを実行します。パイプ、リダイレクト、source venv/bin/activate && …などがすべて機能します。stdout/stderr/exit_codeを返します。出力はストリームごとに100KBに制限されます。完全なトランスクリプトは常にファイルに保存され、パスがlog_pathとして返されます。

read_file(path, offset?, limit?)

オプションの行範囲指定でテキストファイルを読み取ります。

list_directory(path)

タイプ(ファイル/ディレクトリ)、サイズ、mtimeを含むエントリを一覧表示します。

write_file(path, content, overwrite?)

テキストファイルを作成または上書きします。親ディレクトリも作成されます。

run_background(command, cwd?)

デタッチされたサブプロセスを生成し、job_idを返します。チャットをブロックしたくない長時間実行される作業(ビルド、トレーニング実行、サーバーなど)に使用します。

read_background(job_id, tail?)

バックグラウンドジョブのステータスと、stdout/stderrの最後のN行を読み取ります。

list_background()

すべてのジョブ(実行中、終了、強制終了)を一覧表示します。

kill_background(job_id)

ジョブにSIGTERMを送信します。5秒経過しても生存している場合はSIGKILLを送信します。

実行状態(トランスクリプト、ジョブの一時ファイル)は/tmp/claude-term-mcp/以下に保存され、再起動時に消去されます。


インストール

  1. Releasesページから最新のTerminal.mcpbをダウンロードします。

  2. Claude Desktop → Settings → Extensions を開きます。

  3. 下部にある Extension Developer セクションまでスクロールします。Install Extension をクリックし、ダウンロードしたTerminal.mcpbファイルを選択します。

  4. Claude Desktopに「開発者情報がAnthropicによって検証されていません」という赤い警告とともに拡張機能の詳細が表示されます。ソースを信頼できることを確認し、Install をクリックします。

  5. インストール時にClaude Desktopから Default working directory(デフォルトの作業ディレクトリ)を尋ねられます。これは、Claudeが指定しなかった場合にシェルコマンドが実行される場所です。メインのプロジェクトフォルダを選択するか、空のままにしてホームディレクトリをデフォルトにします。

  6. All extensions に戻り、Terminal がオンになっていることを確認します。

  7. チャット内でコネクタ/ツールピッカーを開き、その会話で Terminal を有効にします。

デフォルトの作業ディレクトリは、後から Settings → Extensions → Terminal で変更できます。

要件

  • Linux上のClaude Desktop ≥ 0.10.0(macOSでもテスト済み)

  • Node.js ≥ 16(Claude Desktopには拡張機能実行用のNodeが同梱されているため、システム側のNodeは不要です)

  • PATH上のbash

npm installの手順は不要です。この拡張機能は依存関係ゼロの純粋なNode.jsで構成されています。


設定

すべての設定は、インストール時または Settings → Extensions → Terminal からClaude DesktopのUIを通じて行います。

フィールド

型

目的

Default working directory

ディレクトリ

Claudeが指定しなかった場合にシェルコマンドが実行される場所。空欄にすると$HOMEになります。

拒否リストやその他の動作をカスタマイズするには、server.jsを編集して再ビルドしてください(下記参照)。


既知の問題

黄色いバナー: "Tool result could not be submitted. The request may have expired or the connection was interrupted." これは、Claudeの動的なツール読み込みステップをトリガーするすべてのターンで発生します。この404エラーはAnthropicバックエンドへのツール検索結果送信に関するもので、MCPツール自体に対するものではありません。ツール呼び出しは実行され、バナーの直後に正しく結果が返されます。これは見た目上の問題です。同様の問題は標準のFilesystem拡張機能でも発生します。将来のClaude Desktopリリースで修正される予定の、クライアントとバックエンド間のプロトコルの不一致である可能性が高いです。


ソースからのビルド

git clone https://github.com/LukeLamb/claude-terminal-mcp
cd claude-terminal-mcp

# Edit whatever you want in server.js / manifest.json.
# If you change the tool surface, update both places.

# Bump the version in manifest.json so Claude Desktop treats the install as an update.

# Build the bundle:
zip -j Terminal.mcpb manifest.json package.json server.js

# Then install Terminal.mcpb via Claude Desktop → Settings → Extensions → Install Extension.

アンインストール

Settings → Extensions → All extensions → Terminal → Remove。

プライバシーポリシー

データがマシンから外部へ送信されることはありません。 この拡張機能は完全にローカルで動作します:

  • データ収集: なし。この拡張機能は外部への通信、テレメトリの送信、独自のネットワークリクエストの実行を行いません。観測されるすべてのネットワーク呼び出しは、ユーザーがClaudeに実行を依頼したもの(例: curl、wget、git push)です。

  • データの使用と保存: コマンドのトランスクリプト(stdinは除外、stdout + stderr + 終了コード)は/tmp/claude-term-mcp/runs/<timestamp>.logに書き込まれ、Claudeが同じ会話内で後から参照できるようにします。バックグラウンドジョブの状態(コマンド、pid、stdout/stderrログファイル、終了コード、ステータス)は/tmp/claude-term-mcp/jobs/<job-id>/に書き込まれます。

  • 第三者への共有: なし。この拡張機能によってAnthropic、拡張機能の作成者、または第三者にデータが送信されることはありません。(Claude Desktop自体は、通常のチャットフローの一部としてツールへの入力/出力をAnthropicに送信しますが、これはAnthropicとユーザー間の関係であり、この拡張機能とは無関係です。)

  • 保持: /tmp/claude-term-mcp/は再起動のたびにクリアされます。手動でクリアするには rm -rf /tmp/claude-term-mcp を実行してください。

  • 権限の範囲: コマンドはユーザー自身の権限で実行されます。ターミナルに直接入力した場合と同じです。

  • 連絡先 / 質問: https://github.com/LukeLamb/claude-terminal-mcp/issues でIssueを作成してください。

ライセンス

MIT。自由に使用してください。帰属表示を歓迎しますが、保証はありません。

Available Tools

8 tools
kill_backgroundA
Destructive

Terminate a running background job (SIGTERM, then SIGKILL after 5s).

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYes

TDQS

A3.8/5.0
Behavior4/5

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

Annotations provide destructiveHint=true, and the description adds specific behavioral details (SIGTERM then SIGKILL after 5s), which goes beyond the annotation. No contradiction.

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 a single sentence that is concise and front-loaded with the core purpose and key details. No unnecessary words.

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

Completeness3/5

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

Given the simplicity of the tool (one parameter, no output schema, destructiveHint annotation), the description covers the main behavior but lacks information on error handling, return values, or what happens if the job_id is invalid.

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

Parameters2/5

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

The schema has one parameter (job_id) with no description (0% coverage), and the description does not elaborate on this parameter or its format. The description adds no extra meaning 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 action ('terminate') and the resource ('running background job'), and explicitly mentions the signal sequence (SIGTERM then SIGKILL after 5s). This distinguishes it from sibling tools like list_background and run_background.

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

Usage Guidelines3/5

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

The description implies use for forceful termination but does not explicitly state when to use this tool versus alternatives, nor does it provide any exclusions or prerequisites. The context of sibling names provides some guidance, but it is not stated.

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

list_backgroundA
Read-only

List all background jobs (running, exited, killed).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already indicate readOnlyHint=true, and the description confirms this is a list operation. It adds behavioral context by specifying the job states included (running, exited, killed), which annotations do not cover.

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 a single concise sentence with 8 words, front-loading the purpose. Every word adds value, and there is no extraneous information.

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 simple list tool with no output schema, the description covers what the tool does and the states returned. However, it lacks details on the output structure (e.g., fields like job ID or status), which would help an agent interpret results without schema.

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 input schema has zero parameters and 100% coverage. The description correctly omits parameter details as none exist. No additional parameter info is needed 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 'List all background jobs' with specific states (running, exited, killed). The verb 'List' and resource 'background jobs' are unambiguous, and the states differentiate it from siblings like kill_background or run_background.

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 implies usage when an agent needs to view all background jobs, but it does not provide explicit guidance on when to use this tool versus alternatives like read_background for job details or kill_background for termination.

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

list_directoryA
Read-only

List entries in a directory with type, size, and mtime.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds value by explicitly listing the fields returned (type, size, mtime), which is beyond the annotations. No contradictions.

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?

A single sentence that is clear and to the point, front-loading the purpose and output fields. No wasted words.

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

Completeness3/5

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

For a simple listing tool with one parameter and no output schema, the description covers the basics but lacks details about error handling, recursion, symlinks, or output structure. Given the low complexity, it is minimally viable but could be improved.

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

Parameters2/5

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

The single parameter 'path' has no description in the schema (0% coverage), and the tool description does not clarify the expected format (absolute/relative), allowed values, or behavior for missing paths. The parameter name is self-explanatory, but the description should compensate for the missing schema documentation.

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 action ('list') and resource ('directory entries') and specifies the output fields (type, size, mtime), which distinguishes it from siblings like read_file that read file contents.

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

Usage Guidelines3/5

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

No explicit guidelines on when to use vs alternatives. While the function is straightforward, the description does not mention when not to use or provide context about prerequisites (e.g., path must exist).

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

read_backgroundA
Read-only

Read status and last N lines of stdout/stderr for a background job. tail=0 returns full logs.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYes
tailNoNumber of trailing lines to return. Default 100.

TDQS

A3.9/5.0
Behavior4/5

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

Annotations provide readOnlyHint=true, indicating safety. Description adds detail about reading stdout/stderr and the tail=0 behavior for full logs, enhancing transparency without contradictions.

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?

Two sentences with no fluff. Front-loaded with verb and resource, efficiently conveying core functionality and a key parameter behavior.

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

Completeness3/5

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

No output schema exists, so description should clarify return format. It mentions 'status and last N lines' but lacks specifics on structure, leaving some ambiguity.

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?

Schema coverage is 50% (only tail has description). The description adds value for tail ('tail=0 returns full logs') but does not describe job_id beyond context of 'background job'. Partially compensates for gaps.

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 'Read status and last N lines of stdout/stderr for a background job', specifying the verb and resource. It distinguishes from sibling tools like kill_background (kill) and run_background (start).

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

Usage Guidelines3/5

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

Implies usage for reading background job output but lacks explicit when-to-use or when-not-to-use guidance. No mention of alternatives like read_file for non-job outputs.

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

read_fileA
Read-only

Read a text file with optional line-range slicing.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
offsetNo0-indexed starting line. Default 0.
limitNoMax lines to return. Default 2000.

TDQS

A3.9/5.0
Behavior3/5

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

Annotations already provide readOnlyHint=true, indicating non-destructive behavior. The description adds the line-range slicing behavior, which is not covered by annotations. However, it does not disclose other behavioral traits like encoding assumptions, file existence errors, or output format. With annotations covering safety, this is adequate but not thorough.

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 a single sentence of 8 words, with no unnecessary verbiage. It is front-loaded with the core action and concisely adds scope. Every word earns its place.

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

Completeness3/5

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

Given no output schema and the tool's simplicity, the description covers the input and basic behavior. However, it omits details like return format (list of strings?), error handling (e.g., file not found), or constraints (e.g., file must be UTF-8). It is minimally adequate but could be more 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?

Schema description coverage is 67% (offset and limit have descriptions, path does not). The description mentions 'line-range slicing', which reinforces offset and limit, but does not explicitly describe the path parameter beyond implying it refers to a text file. It adds some context but does not fully compensate for the missing schema description on path.

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 'Read a text file with optional line-range slicing' uses a specific verb (Read) and resource (text file), and adds the line-range slicing detail that distinguishes it from sibling tools like write_file or list_directory. It clearly communicates the tool's primary function.

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 implies usage for reading text files, optionally with line-range slicing. However, it does not explicitly state when not to use this tool or mention alternatives (e.g., using run_command with cat). The context is clear but lacks exclusion guidance, so a 4 is appropriate.

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

run_backgroundA
Destructive

Start a long-running command in the background. Returns a job_id you can poll with read_background.

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYes
cwdNo

TDQS

A3.9/5.0
Behavior4/5

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

Adds 'long-running' context and return of job_id beyond annotations (destructiveHint, openWorldHint). Does not contradict annotations.

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?

Single sentence is concise and front-loaded, but could benefit from structured listing of parameters.

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

Completeness3/5

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

Lacks mentions of kill_background for cancellation or list_background for querying. No output schema so return format (job_id type) is unspecified.

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

Parameters2/5

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

With 0% schema description coverage, description provides no additional meaning for 'command' or 'cwd' parameters.

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?

Description clearly states verb 'Start', resource 'long-running command in the background', and output 'job_id' for polling. Distinguishes from siblings like read_background.

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?

Mentions polling via read_background, guiding usage. Could explicitly contrast with run_command for foreground tasks.

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

run_commandA
Destructive

Run a shell command via bash -lc on the user's machine. Returns stdout/stderr/exit_code. Default cwd is the user-configured default working directory (or $HOME if unset). Output capped at 100KB per stream; full transcript saved to log_path.

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesShell command to run. Pipes, redirects, `source venv/bin/activate && …` all work.
cwdNoWorking directory. Defaults to the user-configured default working directory (or the user's home directory if unset).
timeoutNoTimeout in seconds. Default 120.
envNoExtra environment variables to set for this command.

TDQS

A3.8/5.0
Behavior4/5

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

Adds useful behavioral details beyond annotations: output capped at 100KB, full transcript saved to log_path, default cwd behavior, and use of bash -lc. Does not contradict destructiveHint or openWorldHint.

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?

Three sentences efficiently convey purpose, execution method, defaults, and output limits. Front-loaded with key information, no wasted words.

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?

Covers core functionality, defaults, and output limits. Could mention blocking nature or security implications, but given no output schema and good annotations, it's reasonably 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?

Schema covers all parameters (100% coverage). Description adds minor value for 'command' parameter (notes pipes/redirects work) but otherwise repeats schema info. Baseline 3 is appropriate.

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?

Clearly states the tool runs a shell command via bash -lc, returns stdout/stderr/exit_code. Distinguishes from sibling tools like list_directory or kill_background by focusing on command execution.

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

Usage Guidelines2/5

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

No explicit guidance on when to use this vs alternatives like run_background or read_file. The description only states what it does, not when to prefer it over siblings.

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

write_fileA
Destructive

Create or overwrite a text file. Parent directories are created.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
contentYes
overwriteNoDefault true.

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already mark destructiveHint=true. The description adds that parent directories are created, providing useful behavioral context beyond the annotation. It does not mention file size limits or encoding, but for a simple write tool this is adequate.

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?

Two succinct sentences with no unnecessary words. The key action and side effect (parent directory creation) are front-loaded.

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

Completeness3/5

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

The description covers core functionality but omits edge cases (e.g., behavior when overwrite is false and file exists). With no output schema, the side effects and return values are not disclosed. Overall minimal viable but with gaps.

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

Parameters2/5

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

Schema description coverage is only 33% (only overwrite has a description). The tool description does not elaborate on path or content parameters, failing to compensate for the low coverage. The description only implies content is text, no parameter-specific details.

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 'Create or overwrite a text file' with a specific verb and resource. The additional detail about parent directories being created distinguishes it from siblings like read_file and run_command.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives such as run_command or read_file. The description omits when not to use it or mention of trade-offs.

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. 8 tool updatesv0.1.0
    • First observedkill_background
    • First observedlist_background
    • First observedlist_directory
    • First observedread_background
    • First observedread_file
    • First observedrun_background
    • First observedrun_command
    • First observedwrite_file

TDQS

A4.1/5.0

Scored across 8 tools

Disambiguation5/5

Each tool has a distinct purpose: run_command for synchronous commands, run_background for long-running, and separate tools for file operations and background job management. No overlap.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (e.g., kill_background, list_directory, read_file), making the set predictable.

Tool Count5/5

With 8 tools, the server covers essential terminal operations (command execution, file read/write, listing, background jobs) without excessive tool count.

Completeness4/5

Core operations are present, but missing file deletion, rename, and persistent directory change tools; however, these can be accomplished via run_command, so only minor gaps.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    B
    maintenance
    Give Claude Desktop full desktop control on Linux/X11: screenshot, mouse, keyboard, windows, clipboard, app launch. Zero-dependency MCP extension, MIT-licensed.
    15
    MIT
  • A
    license
    Not graded
    quality
    B
    maintenance
    Exposes an interactive terminal over MCP, enabling remote shell command execution, file operations, and directory management via ChatGPT or Claude Desktop.
    2
    MIT