unmcp

Skip MCP. Enjoy CLI.

Use MCP server tools directly from your terminal. Perfect for scripting, automation, and agentic workflows.

Compatibility: Expected to work with most MCP servers out of the box—just point it at any stdio-based MCP server and go.

Quick Start

# 1. Configure your MCP servers in .unmcp/.mcp.json
# 2. Initialize a server (discovers available tools)
uvx unmcp clt init 

# 3. Call tools directly
uvx unmcp   [OPTIONS]

Why unmcp?

MCP servers offer powerful, structured tools. But the MCP protocol loads large tool schemas and verbose data into AI context—expensive in tokens, slow in practice.

CLI is leaner. It avoids loading tool schemas and verbose outputs into model context.

unmcp gives you direct CLI access to MCP server tools. Same tools, no protocol overhead.

Not every MCP server has an official CLI. Rather than waiting, unmcp lets you use existing MCP servers as CLIs right now.

See Playwright CLI vs MCP for a similar motivation.

Usage

Server Management

uvx unmcp clt init       # Initialize and discover tools (--force to reinitialize)
uvx unmcp clt list               # List servers with status
uvx unmcp clt start      # Start persistent daemon
uvx unmcp clt stop       # Stop daemon

Calling Tools

Argument names match the MCP tool schema exactly (e.g., libraryId becomes --libraryId).

# Basic call
uvx unmcp   --arg1 "value"

# Output as JSON (flag before tool name)
uvx unmcp  --json  --arg1 "value"

# Save to file (flag before tool name)
uvx unmcp  --output result.json  --arg1 "value"

# Save to directory (auto-generates filename: {server}_{tool}_{timestamp}.json)
uvx unmcp  --output ./output_dir/  --arg1 "value"

# View available tools
uvx unmcp  --help

# View tool options
uvx unmcp   --help

Execution Modes

On-Demand Mode

Each tool call spawns a new MCP server, executes the tool, and exits.

When to use: The MCP server starts quickly, tool calls are infrequent, or the server is stateless. Avoids keeping extra processes running.

sequenceDiagram
    participant CLI as uvx unmcp
    participant MCP as MCP Server

    CLI->>MCP: spawn process
    CLI->>MCP: initialize + call_tool()
    MCP-->>CLI: result
    CLI->>MCP: exit

Daemon Mode

A daemon process keeps the MCP server running. Tool calls connect via Unix socket.

When to use: Making many tool calls in succession, the server has slow startup, or the server maintains state between calls.

sequenceDiagram
    participant CLI as uvx unmcp
    participant D as Daemon
    participant MCP as MCP Server

    Note over CLI,MCP: uvx unmcp clt start
    D->>MCP: spawn & initialize
    D->>D: listen on socket

    Note over CLI,MCP: uvx unmcp