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, #debug, and more

Installation

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.1.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

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

Publishing to PyPI

Releases are published by the Publish GitHub Actions workflow (.github/workflows/publish.yml) using PyPI Trusted Publishing (OIDC), so no API tokens are stored anywhere.

One-time setup on https://pypi.org (and https://test.pypi.org for dry runs), under Account → Publishing → Add a pending publisher:

To release:

1. Bump version in pyproject.toml (PyPI never accepts the same version twice).
2. Dry run: Actions → Publish → Run workflow → target testpypi, then install from TestPyPI: uv tool install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ mcphee
3. Publish: create a GitHub Release tagged vX.Y.Z — the workflow uploads to PyPI.

To build locally without publishing: uv build (writes dist/mcphee-*.whl and .tar.gz).

License

MIT