remote-mcp-cli 0.8.0

Minimal MCP client CLI

remote-mcp-cli

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, which can now use any MCP server through the terminal.

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. Set environment variables (for protected servers)

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 remote-mcp-cli init

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

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

Traditional Installation

You can also install traditionally with uv:

uv pip install remote-mcp-cli

💡 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 remote-mcp-cli call context7 resolve-library-id '{"libraryName":"react"}'

CLI Architecture

remote-mcp-cli 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 remote-mcp-cli init

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

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

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

Config-Based Examples

Step 1: Initialize tools from config

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

Step 2: Use simplified interface

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

# Call tools by alias - credentials come from environment
uvx remote-mcp-cli call context7 resolve-library-id '{"libraryName":"react"}'
uvx remote-mcp-cli 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 remote-mcp-cli 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 remote-mcp-cli 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 remote-mcp-cli direct list --url https://mcp.deepwiki.com/mcp

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

# Bearer token authentication
uvx remote-mcp-cli 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 remote-mcp-cli --help

# Help for specific commands
uvx remote-mcp-cli init --help
uvx remote-mcp-cli list --help
uvx remote-mcp-cli call --help
uvx remote-mcp-cli 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