mcp-cli

mcp-cli is a CLI inspector for the Model Context Protocol. It lets you run MCP servers sourced from npm packages, local Node.js servers, or remote HTTP endpoints using Streamable HTTP or SSE. You can list available tools, resources, and prompts, and you can invoke tools or read resources and prompts directly from the command line. The tool supports non-interactive mode, allowing you to script calls to specific primitives, and it can purge stored OAuth tokens and other data when needed.

To use it, you typically run the CLI with npx, which will load the mcp-cli package and connect to a target MCP server. You can start servers from npm packages with commands like npx @wong2/mcp-cli npx <package-name> <args>, run a locally developed server with npx @wong2/mcp-cli node path/to/server/index.js, or connect to an already-running server via URL or SSE endpoints. The non-interactive mode lets you execute a specific tool, resource, or prompt without prompts by providing a command, server name, and target (for example, filesystem:list_files) along with JSON-encoded arguments.

Common workflows include:

• Discovering available primitives (tools, resources, prompts) on a given MCP server.
• Calling a tool with or without arguments to obtain results.
• Reading a resource or using a prompt to generate or transform content.
• Scripting interactions by using the non-interactive invocation format and, if necessary, purging stored OAuth tokens.

Prerequisites:

• Node.js (LTS recommended) and npm/yarn installed on your machine.
• Internet access to install the MCP CLI via npx.

Installation steps:

1. Ensure you have Node.js and npm installed. You can verify with: node -v npm -v

2. Install or run the MCP CLI via npx (no global install required): npx @wong2/mcp-cli

3. If you prefer to install locally for repeated use, you can install temporarily in a project: npm init -y npm install @wong2/mcp-cli --save-exact ./node_modules/.bin/mcp-cli

4. Verify installation by listing or connecting to a server, for example: npx @wong2/mcp-cli

Notes:

• If you are behind a firewall or require a specific Node version, ensure the environment is configured accordingly.
• For scripting, prefer the non-interactive mode to avoid prompts and specify the target primitive explicitly.

Tips and common issues:

• When using a config file, ensure it follows the same format as the Claude Desktop config file referenced by the project.
• To connect to an external server, you can use --url <server-url> or --sse <server-url> for Streamable HTTP or SSE streams respectively.
• Use purge to clear OAuth tokens or other stored credentials if you encounter authentication issues.
• If you encounter npm/npx resolution issues, try clearing npm cache or using a local installation instead of npx.
• The CLI supports running servers from npm packages as well as locally developed servers, enabling flexible experimentation with different MCP implementations.