cli-mcp 0.18.0

Minimal MCP client CLI

cli-mcp

A minimal command-line MCP client that makes it easy to call tools from local (stdio) and remote (Streamable HTTP) MCP servers using terminal commands. This project was created to add MCP support for coding agents like OpenAI's Codex.

Works with your project's existing Cursor mcp.json config file.

Quick Start

1. Set up your MCP config file

Create ./.cursor/mcp.json (or ./mcp.json at project root) with your MCP servers:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    },
    "ref": {
      "command": "bunx",
      "args": ["-y", "ref-tools-mcp@latest"],
      "env": {
        "REF_API_KEY": "your-api-key-here"
      }
    }
  }
}

2. (Optional) Set environment variables

If your environment variables are already in your mcp.json file, you can skip this step. They will automatically be parsed and added to the environment.

export REF_API_KEY="your-actual-api-key"

3. Go!

# Reads config and creates/updates mcp_tools.txt with all available tools, schemas, and example commands.
uvx cli-mcp init

# List tools by server alias
uvx cli-mcp list context7

# Call tools by server alias - no URLs or API keys needed!
uvx cli-mcp call context7 resolve-library-id '{"libraryName":"react"}'
uvx cli-mcp call ref ref_search_documentation '{"query":"nextjs caching"}'

Traditional Installation

You can also install traditionally with uv:

uv pip install cli-mcp

💡 Tip: The simplified interface works great with AI assistants! Tell your agent to read mcp_tools.txt to understand which tools are available, and it can call tools using commands like uvx cli-mcp call context7 resolve-library-id '{"libraryName":"react"}'

CLI Architecture

cli-mcp features a clean 4-command interface:

1. init - Discovers all servers from your MCP config and generates mcp_tools.txt with all available tools, schemas, and example commands.
2. list <server-alias> - Lists available tools for a single server from mcp.json
3. call <server-alias> <tool-name> <args> - Call a tool
4. direct - Direct URL access for remote servers (no config needed)

Config File Discovery

The CLI automatically finds your MCP config in this priority order:

1. .cursor/mcp.json (Cursor IDE projects)
2. mcp.json (global fallback)
3. --configpath (explicit path)

If none of these are found, the init command will fail.

Server Types Supported

Remote MCP servers (Modern MCP 2025-06-18 spec):

• Zero setup: Just add the URL to your config
• Automatic transport: Supports both modern Streamable HTTP and legacy REST
• Built-in auth: Headers and bearer tokens from config
• Examples: Context7, ref-tools, custom HTTP servers

Local MCP servers (stdio):

• npx/bunx integration: Automatically spawns and manages processes
• Environment security: Validates required env vars are set in terminal
• Auto-detection: Tries HTTP first, falls back to stdio if needed
• Examples: Any bunx or npx MCP package

Features

• 🎯 Simplified Interface: Use server aliases instead of URLs and API keys
• 🔒 Environment Security: Validates API keys are set in terminal environment
• 📁 Config Discovery: Automatically finds .cursor/mcp.json or mcp.json
• 🚀 Auto Transport: Detects HTTP vs stdio and chooses the best transport
• 📋 Tool Discovery: init command generates mcp_tools.txt with all available tools
• ⚡ Modern MCP: Full support for MCP Streamable HTTP transport (2025-06-18 spec)
• 🔄 Legacy Support: Automatically falls back to older REST endpoints
• 🎨 Rich Schemas: Shows parameter names, types, and required fields

Usage

Core Commands

# Initialize all tools from MCP config into mcp_tools.txt
uvx cli-mcp init

# List tools by server alias (from config)
uvx cli-mcp list <server-alias>

# Call tools by server alias (from config)
uvx cli-mcp call <server-alias> <tool-name> <json-args>

# Direct URL access (no config needed)
uvx cli-mcp direct list --url <server-url>
uvx cli-mcp direct call --url <server-url> <tool-name> <json-args>

Config-Based Examples

Step 1: Initialize tools from config

uvx cli-mcp init
# ✓ Processed 2 servers successfully
# → mcp_tools.txt written with 5 tools total

Step 2: Use simplified interface

# List tools by alias
uvx cli-mcp list context7

# Call tools by alias - credentials come from environment
uvx cli-mcp call context7 resolve-library-id '{"libraryName":"react"}'
uvx cli-mcp call ref ref_search_documentation '{"query":"nextjs"}'

Generated mcp_tools.txt shows all available tools:

### Server: context7  (https://mcp.context7.com/mcp)
- resolve-library-id: Resolves a package/product name to a Context7-compatible library ID...
  Parameters: *libraryName(string)
  (* = required)
  Example: uvx cli-mcp call context7 resolve-library-id '{"libraryName": "VALUE"}'

### Server: ref  (local npx, stdio)
- ref_search_documentation: A powerful search tool to check technical documentation...
  Parameters: *query(string)
  (* = required)
  Example: uvx cli-mcp call ref ref_search_documentation '{"query": "VALUE"}'

Configuration File Format

Remote servers (HTTP/HTTPS):

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    },
    "authenticated-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token",
        "x-api-key": "your-key"
      }
    }
  }
}

Local servers (stdio):

{
  "mcpServers": {
    "ref": {
      "command": "bunx",
      "args": ["-y", "ref-tools-mcp@latest"],
      "env": {
        "REF_API_KEY": "ref_1234567890abcdef"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    }
  }
}

Environment Variable Security: The CLI validates that environment variables (like REF_API_KEY) are actually set in your terminal before connecting. This prevents accidentally using placeholder values from the config file.

Direct URL Access (No Config)

For one-off usage without setting up a config file, use the direct command:

# List tools directly
uvx cli-mcp direct list --url https://mcp.deepwiki.com/mcp

# Call tools directly with authentication
uvx cli-mcp direct call \
  --url https://api.ref.tools/mcp \
  --header "x-ref-api-key: YOUR_KEY" \
  read_documentation \
  '{"query": "nextjs routing"}'

# Bearer token authentication
uvx cli-mcp direct list \
  --url https://secure-server.com/mcp \
  --bearer "your-token"

Transport Priority

The CLI automatically detects and tries transports in this order:

1. Streamable HTTP (modern MCP 2025-06-18 spec)
2. Legacy REST (older /manifest, /call_tool endpoints)
3. Stdio JSON-RPC (for local spawned servers)

Help & Support

# Get overall help
uvx cli-mcp --help

# Help for specific commands
uvx cli-mcp init --help
uvx cli-mcp list --help
uvx cli-mcp call --help
uvx cli-mcp direct --help

Development

Building and Publishing

To build and publish the package with uv:

uv build
uv pip install --system twine
uv twine upload dist/*

MCP Protocol Support

This CLI implements:

• MCP Protocol Version: 2025-06-18
• JSON-RPC 2.0 message format over stdio
• Streamable HTTP transport with SSE support
• Session management via Mcp-Session-Id headers
• Proper initialization handshake
• Tool discovery and execution
• Environment variable validation for security