mcpal

Inspect, call, and script any MCP server — over stdio or HTTP, with OAuth, from one CLI.
_{The curl-equivalent for the Model Context Protocol.}

Quickstart • Install • Examples • Docs

Your editors (Claude Desktop, Cursor, Zed, opencode) configure dozens of MCP servers — GitHub, Linear, Notion, a filesystem sandbox. Once configured, the only way to drive them is from inside that chat app. mcpal is the shell tool that was missing: point it at any server and call tools, read resources, get prompts, run raw JSON-RPC, or stream notifications.

Why

• Debug servers you're building. tool call, tool describe, raw, watch against the server you just started — no chat-UI round-trip.
• Script integrations in CI. A nightly job that pulls Linear tickets or files a GitHub issue, through the same servers your editors use.
• Call already-configured servers. Cursor set up linear? Run mcpal tool list cursor:linear. No copy-pasting mcp.json.
• Skip the upfront tool-definition tax. A chat app loads every server's full tool catalogue into the model's context. mcpal invokes one tool per shell line — pay for what you call. More in Why a CLI for MCP.

Quickstart

One-liner — no setup

# any stdio MCP server, ephemeral
mcpal tool call "cmd:npx -y @modelcontextprotocol/server-everything" \
    echo --message hi

# anonymous HTTP server
mcpal --auth none tool list https://mcp.context7.com/mcp

# HTTP + env-backed bearer (no token in shell history)
GH_TOKEN=ghp_… mcpal --auth env:GH_TOKEN \
    tool list https://api.githubcopilot.com/mcp/

Full table of one-line <ref> shapes: One-line MCP.

Call a server your editor already configured

mcpal server discover                       # what's installed where
mcpal tool list cursor:linear --names-only
mcpal tool call cursor:linear get-issue --id ENG-123

Add your own

# stdio
mcpal server add ev -- npx -y @modelcontextprotocol/server-everything
mcpal tool call ev echo --message hi

# HTTP + bearer (literal token → OS keyring)
mcpal server add gh --http https://api.githubcopilot.com/mcp/ --bearer $GH_TOKEN

# HTTP + OAuth 2.1 (PKCE + DCR) — browser opens inline
mcpal server add notion --http https://mcp.notion.com/v1 --oauth
mcpal tool list notion

Browse interactively

mcpal tui                                   # split-pane MCP browser

Run a saved call

# Repo has mcpal.yml at root
mcpal run get-issue --profile prod

Tapes that produce these GIFs live in demo/.

Install

Platform	One-liner
macOS / Linux	brew install pawelb0/tap/mcpal
Debian / Ubuntu	curl -fsSLO …/releases/latest/download/mcpal_amd64.deb && sudo dpkg -i mcpal_amd64.deb
Any (Rust)	cargo install --git https://github.com/pawelb0/mcpal --path crates/mcpal
Windows	cargo install --git https://github.com/pawelb0/mcpal --path crates/mcpal

Full guide — .deb URL, curl | sh installer, shell completions, verify — in the Install chapter.

Synopsis

mcpal <command> [<ref>] [options]

A <ref> is one of:

• a name registered with mcpal server add
• <source>:<name> from mcpal server discover (e.g. cursor:linear)
• a bare <name> if unambiguous across discovered sources
• an https:// URL
• a path to a JSON ServerSpec

mcpal discover reads the MCP server lists that other clients (Claude Desktop, Cursor, opencode, ...) already wrote to disk; those servers are addressable directly.

Examples

Inspect a server:

mcpal server ping ev
mcpal server capabilities ev
mcpal tool describe ev echo

Call a tool (flags, JSON, or stdin):

mcpal tool call ev echo --message hi
mcpal tool call ev echo --params '{"message":"hi"}'
echo '{"message":"hi"}' | mcpal tool call ev echo --params -

HTTP with a bearer token:

mcpal server add github --http https://api.githubcopilot.com/mcp/ --bearer ghp_xxx
mcpal tool list github

Resources, prompts, notifications:

mcpal resource read ev demo://resource/static/document/architecture.md
mcpal prompt get ev args-prompt --city Dallas --state Texas
mcpal watch ev                          # one YAML doc per event

Pipelines and diagnostics:

mcpal --output json tool list ev | jq -r '.[].name'
mcpal --query '[].name' tool list ev
mcpal debug doctor

Full command reference, recipes, and the protocol compliance matrix live in the manual.

Configuration

~/.config/mcpal/config.toml on Linux, ~/Library/Application Support/mcpal/config.toml on macOS, %APPDATA%\mcpal\config.toml on Windows. Override with MCPAL_CONFIG=/path/to/file.

[server.everything]
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-everything"]

[server.notion]
transport = "http"
url = "https://mcp.notion.com/v1"
auth = { type = "bearer_env", env = "NOTION_MCP_TOKEN" }

Secrets do not live in this file. mcpal auth login writes them to the OS keyring.

License

MIT