remote-mcp-cli 0.8.0
Minimal MCP client CLI
Requires Python: >=3.8

# 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:

```json
{
  "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)

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

### 3. Go!

```bash
# 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](https://github.com/astral-sh/uv):

```bash
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

```bash
# 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**
```bash
uvx remote-mcp-cli init
# ✓ Processed 2 servers successfully
# → mcp_tools.txt written with 5 tools total
```

**Step 2: Use simplified interface**
```bash
# 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):
```json
{
  "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):
```json
{
  "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:

```bash
# 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

```bash
# 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`:

```bash
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