/ 
App-MCP-CLI-v0.0.1
/ mcpcli

NAME

mcpcli - Command-line client for Model Context Protocol (MCP) servers

VERSION

This script is distributed as part of App::MCP::CLI v0.0.1.

SYNOPSIS

mcpcli <command> [options]

# List all servers defined in the config file
mcpcli servers --config server_config.json

# List all tools exposed by a server
mcpcli list --config server_config.json --server perl-math-server

# Call a specific tool with inline arguments
mcpcli call add_numbers --config server_config.json --server perl-math-server a=10 b=5

# Call a tool interactively (prompted for arguments)
mcpcli call add_numbers --config server_config.json --server perl-math-server

# Start an interactive agent chat session
mcpcli interactive --config server_config.json --server perl-math-server

# Alias: chat and interactive are identical
mcpcli chat --config server_config.json --server perl-math-server

# Print version
mcpcli --version
mcpcli -V
mcpcli version

# Built-in help
mcpcli help
mcpcli help <command>

DESCRIPTION

mcpcli is a Perl implementation of a command-line client for servers that implement the Model Context Protocol (MCP) - a JSON-RPC 2.0-based protocol for exposing callable tools to AI agents and other automation clients.

It provides a suite of sub-commands for discovering, inspecting, and invoking MCP tools, as well as an interactive agent shell that routes natural-language queries through a local LLM (currently Ollama) to the appropriate tool.

COMMANDS

servers

List all servers defined in the configuration file.

mcpcli servers [--config <file>]
list

List all tools exposed by a specific MCP server.

mcpcli list [--server <name>] [--config <file>] [--timeout <seconds>]
call

Invoke a specific tool on an MCP server. Arguments may be supplied inline as key=value pairs, or omitted to enter interactive mode where the tool's input schema is inspected and the user is prompted for each required field.

mcpcli call <tool_name> [key=value ...] [--server <name>] [--config <file>] [--timeout <seconds>]
interactive (alias: chat)

Start an agent-style REPL that accepts natural-language queries, routes them through a local Ollama LLM, and executes the appropriate MCP tool. Results are summarised by the LLM before being displayed.

mcpcli interactive [--server <name>] [--provider <name>] [--model <name>] [--config <file>] [--timeout <seconds>]
mcpcli chat        [--server <name>] [--provider <name>] [--model <name>] [--config <file>] [--timeout <seconds>]
version

Print the installed version of mcpcli and exit.

mcpcli version
help

Display help for the application or a specific sub-command.

mcpcli help
mcpcli help <command>
commands

List all available sub-commands.

mcpcli commands

GLOBAL OPTIONS

--version, -V

Print the version string and exit immediately.

--help, -h, -?

Display the top-level help screen listing all available commands.

COMMON SUB-COMMAND OPTIONS

The following options are accepted by most sub-commands:

--config|-c path

Path to a JSON configuration file describing available MCP servers. When omitted, the following locations are searched in order:

1. ./server_config.json in the current directory.
2. ./mcp-config.json in the current directory.
3. $HOME/.config/mcp-cli/config.json.
--server|-s name

The name of an MCP server as defined in the mcpServers section of the configuration file. May also be a path to a .pl script, an http:///https:// URL (SSE mode), or a bare shell command string. May be omitted when the configuration file defines exactly one server.

--timeout|-t seconds (default: 30)

How long to wait for each reply from the MCP server (list, call, chat). 0 waits forever.

--provider|-p name (default: ollama)

The LLM provider to use for the interactive/chat commands. Only ollama is currently supported.

--model|-m name (default: qwen2.5:1.5b)

The model tag to pass to the LLM provider.

CONFIGURATION FILE

The JSON configuration file has the following structure:

{
  "confirmTools": true,
  "mcpServers": {
    "perl-math-server": {
      "command": "perl",
      "args": ["stdio_server.pl"],
      "env": { "DEBUG": "1" }
    },
    "remote-server": {
      "url": "http://mcp.example.com/sse"
    }
  }
}
mcpServers (object)

A map of server alias names to server descriptor objects. Each descriptor supports:

command (string) - executable to launch (stdio mode).
args (array) - additional arguments for the executable.
env (object) - environment variables to set before launching.
url (string) - SSE endpoint URL (SSE mode).
transport (string) - set to "sse" to force SSE mode.
confirmTools (boolean, default: true)

When true, the interactive/chat command pauses before executing any tool call and asks the user for explicit confirmation. Set to false to allow autonomous execution.

TRANSPORT MODES

stdio

The server is launched as a child process. Messages are exchanged as newline-delimited JSON on its stdin/stdout. This is the default mode when a command key is present in the server descriptor.

HTTP/SSE

When the server descriptor contains a url key, or when --server is given an http:///https:// URL directly, the client connects in SSE mode (MCP protocol revision 2024-11-05). It opens the event stream with a GET, reads the endpoint event to learn the POST URL, then sends all JSON-RPC messages as POST requests to that URL. Responses are accepted either in the POST reply body or as message events on the stream. This works for list, call and chat. https:// URLs need IO::Socket::SSL.

ENVIRONMENT

HOME / USERPROFILE

Used to locate the default configuration file at $HOME/.config/mcp-cli/config.json when no --config option is given and no local config file is found.

OLLAMA_HOST

Address of the Ollama server used by chat (default http://localhost:11434).

MCPCLI_DEBUG

When set to a true value, every JSON-RPC message sent to or received from the server is printed to STDERR.

DEPENDENCIES

A running Ollama instance (http://localhost:11434 unless OLLAMA_HOST is set) is required for the interactive/chat commands.

EXIT STATUS

0 - success.
1 - any error: usage error or missing argument, invalid configuration, the server could not be started or reached, a timeout, an unknown tool, a JSON-RPC error, or (for call) a tool result flagged isError. The message is printed to STDERR.

Results are written to STDOUT; progress and error messages go to STDERR.

SEE ALSO

AUTHOR

Mohammad Sajid Anwar, <mohammad.anwar at yahoo.com>

REPOSITORY

https://github.com/manwar/App-MCP-CLI

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/manwar/App-MCP-CLI/issues. I will be notified and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc App::MCP::CLI

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright (C) 2026 Mohammad Sajid Anwar.

This program is free software; you can redistribute it and / or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License.By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you,you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement,then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.