mcphee

mcphee is an interactive CLI client for Model Context Protocol (MCP) servers. Connect to any MCP server — local (stdio) or remote (SSE / Streamable HTTP) — and explore its tools, resources, and prompts in a rich interactive REPL.

Features

• Universal transport support — stdio, SSE, and Streamable HTTP
• Interactive REPL — Vi mode (default) or Emacs mode with full line editing
• Tab completion — fuzzy-match tool names, resource URIs, prompt names, and their parameters
• Auto-suggestions — fish-shell style history suggestions as you type
• Persistent history — across sessions, XDG-compliant location
• Named profiles — save connection configs in ~/.config/mcphee/profiles.toml
• Rich output — syntax-highlighted JSON, tables, and panels; toggle to raw JSON with #json
• Meta-commands — #refresh, #export, #timeout, #payload, #debug, #loglevel, and more

Installation

Prerequisite: install uv

mcphee is installed with uv, Astral's Python package and tool manager. uv also downloads a suitable Python (3.11+) automatically if you don't have one, so you don't need to install Python first.

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Or with a package manager: brew install uv (macOS) or winget install --id=astral-sh.uv -e (Windows).

Then open a new terminal and check it works:

uv --version

uv tool install puts commands such as mcphee in ~/.local/bin (Windows: %USERPROFILE%\.local\bin). If mcphee is "command not found" after installing, add that directory to your PATH with:

uv tool update-shell

and open a new terminal.

Recommended: uv tool (isolated, no venv management)

# From PyPI
uv tool install mcphee

# From GitHub (latest main)
uv tool install git+https://github.com/dgwartney/mcphee

# Specific tag or commit
uv tool install "git+https://github.com/dgwartney/mcphee@v0.2.0"

# From a local clone
uv tool install .

After installation the mcphee command is available globally without activating a virtual environment. Upgrade with:

uv tool upgrade mcphee

pip

pip install mcphee

Quick Start

Try it immediately with the bundled example server (no setup):

mcphee connect --demo

TUTORIAL.md walks through it step by step. To connect to your own servers:

# Connect to a local stdio MCP server
mcphee connect --stdio 'npx -y @modelcontextprotocol/server-filesystem /tmp'

# Connect via SSE with an API key header
mcphee connect --sse http://localhost:8080/sse --header x-api-key=secret

# Connect via Streamable HTTP
mcphee connect --http http://localhost:8080/mcp

# Connect using a saved profile
mcphee connect --profile myserver

Once connected you'll enter the interactive REPL:

╭─ mcphee ──────────────────────────────────────────────────────╮
│ Connected via http                                            │
│ http://localhost:8080/mcp                                     │
│ Type help for commands or exit to quit.                       │
╰───────────────────────────────────────────────────────────────╯
> list tools
> call read_file path=/tmp/notes.txt
> list resources
> read file:///tmp/notes.txt
> list prompts
> prompt summarize text="hello world"
> exit

REPL Command Reference

Argument syntax

Tool and prompt arguments are passed as key=value pairs:

> call read_file path=/tmp/foo.txt
> call search query="hello world" limit=10
> prompt summarize text="Some long text here" language=en

Values are automatically typed: true/false to bool, integers to int, JSON arrays/objects to parsed.

Meta-Command Reference

Meta-commands begin with # and control the REPL session:

Profile Management

Save connection configs so you don't have to retype them:

# Add a profile interactively
mcphee profile add myserver

# List all profiles
mcphee profile list

# Remove a profile
mcphee profile remove myserver

Profile TOML schema (~/.config/mcphee/profiles.toml):

[profiles.lumen]
mode = "http"
url = "http://localhost:8080/mcp"
[profiles.lumen.headers]
x-api-key = "secret"

[profiles.filesystem]
mode = "stdio"
command = "npx -y @modelcontextprotocol/server-filesystem /tmp"

[profiles.weather]
mode = "sse"
url = "http://weather-api.internal/sse"

Configuration Paths (XDG)

mcphee follows the XDG Base Directory Specification:

Key Bindings

The REPL uses Vi mode by default. Use --emacs to switch to Emacs mode.

License

MIT