MCP ExplorerExplorer

Mcptool

@tenxhqon 4 days ago
3 MIT
FreeCommunity
AI Systems
A versatile command‑line utility for connecting to, testing, and probing **MCP** servers from your terminal.

Overview

What is Mcptool

mcptool is a developing command-line utility designed for interacting with servers using the MCP protocol. It provides functionalities for connecting to, testing, and probing MCP servers directly from the terminal.

Use cases

mcptool is ideal for developers, system administrators, and CI pipelines that require a reliable toolset for communicating with MCP servers. Use cases include performance measurement, server diagnostics, and automated command execution in development workflows.

How to use

To use mcptool, first install it via cargo with ‘cargo install mcptool’. Then, run commands such as ‘mcptool connect ’ to open an interactive session or ‘mcptool ping ’ to check latency. The utility supports both TCP connections and local stdio processes.

Key features

Key features of mcptool include one-liner connections for quick interactions, health and latency checks with ‘mcptool ping’, capability discovery for exploring server commands, and script-friendly output formats for automation, including JSON and quiet modes.

Where to use

mcptool is suitable for environments where MCP protocol servers are utilized, such as application development and testing settings. It can be employed in both local setups with stdio commands and remote server interactions, aiding in diagnostics and server management tasks.

Content

mcptool is under heavy development and not yet ready for use - check back later!

mcptool

A versatile command‑line utility for connecting to, testing, and probing
MCP servers from your terminal.

mcptool aims to provide a unified Swiss‑army‑knife for developers,
administrators, and CI pipelines that interact with servers speaking the
MCP protocol.

Key Features

  • One‑liner connections – quickly open an interactive MCP session without
    extra setup.
  • Health & latency checks – measure round‑trip times with a simple mcptool ping.
  • Capability discovery – automatically probe which optional commands a
    server supports.
  • Script‑friendly output – machine‑readable JSON and quiet modes for
    automation.

Quick Start

cargo install mcptool

Usage

After installation the binary is available as mcptool. Use --help on any sub‑command for detailed flags.

Target Specification

Every sub‑command that expects a target accepts either a TCP endpoint or
a local command to be spawned in stdio mode.

Variant Syntax What Happens
Implicit TCP (default) host[:port] Connects via TCP. If no port is given, the command‑specific default applies.
Explicit TCP tcp://host[:port] Same as above but unambiguous when the host could contain a scheme prefix.
Stdio Command cmd://<program> [args…] Spawns the program locally and speaks MCP over its STDIN/STDOUT pipes. Use quotes when the command contains spaces.

Example targets

  • api.acme.ai (TCP, default port)
  • tcp://api.acme.ai:7780 (TCP, port 7780)
  • "cmd://./my‑stdio‑server --some --argument" (local process)

Global Commands (run from your shell)

Command Purpose
mcptool connect <target> [--script <file>] Connect to the target. Without --script you drop into an interactive prompt (>). With --script mcptool reads one sub‑command per line from file, executes them sequentially, prints results, and exits.
mcptool proxy <target> --log-file <file> Transparently open a stdio transport, and proxy all traffic to target, recording it to file.
mcptool version Display the mcptool build version & linked MCP revision.
mcptool help [sub-command] Show contextual help for any command.

MCP Commands (usable inside the prompt or from the shell with a <target>)

When you are inside the prompt, type these commands without the mcptool prefix and without a target. From the regular shell, prefix them with mcptool and provide a <target>.

Prompt form Shell form Purpose
ping mcptool ping <target> Measure round‑trip latency.
status mcptool status <target> Fetch server status/handshake info.
probe mcptool probe <target> Run all discovery calls (listtools, listprompts, listresources, listresourcetemplates) and print a complete overview.
listtools mcptool listtools <target> List all MCP tools (tools/list).
listprompts mcptool listprompts <target> List predefined prompt templates (prompts/list).
listresources mcptool listresources <target> List server resources such as databases or file trees (resources/list).
listresourcetemplates mcptool listresourcetemplates <target> List resource templates available for instantiation.
calltool -- <entity> [args…] [--stdin-json] mcptool calltool <target> -- <entity> [args…] [--stdin-json] Invoke a tool, prompt, or resource. Use --stdin-json to pass a JSON object via STDIN.

Interactive Prompt & Script Mode

Once connected without --script, you can run any sub‑command without specifying the target again, just as you would on the normal command line.

If you provide --script mysession.mcp, the file is read line‑by‑line and each line is dispatched exactly as if you had typed it at the prompt. After the last line executes the connection closes automatically.

$ mcptool connect api.acme.ai
Connected to api.acme.ai (tcp, proto‑rev 9)
> ping
107 ms
> listtools
summarize      translate      moderate
> calltool summarize --text "Hello world"
{"summary":"Hello 🌍"}
> exit

Examples

# Check latency to a remote MCP server (implicit TCP)
mcptool ping api.acme.ai

# Check latency to a local stdio server
mcptool ping "cmd://./my‑stdio‑server --some --argument"

# Connect via TCP on a non‑default port and immediately run a status query, then exit
mcptool calltool tcp://dev.acme.ai:7780 -- status

# Execute a tool with arguments on a local stdio endpoint
mcptool calltool "cmd://./my‑stdio‑server --some --argument" -- summarize --text "Hello world"

# Pass a complex JSON payload via STDIN
cat complex_args.json | mcptool calltool api.acme.ai -- chat.complete --stdin-json

# Run a scripted sequence without entering the prompt
mcptool connect api.acme.ai --script mysession.mcp --quiet | mcptool calltool api.acme.ai -- chat.complete --stdin-json

Tools

No tools

Comments