0xrichardh/mcporter

mcporter

CLI for calling MCP servers directly. Use npx mcporter — no global install required.

Quick Start

npx mcporter list                           # List all configured servers
npx mcporter list <server>                  # Show server tools with signatures
npx mcporter call <server>.<tool> key=val   # Call a tool
npx mcporter config list                    # Show current configuration

Configuration

Default config: $HOME/.config/mcporter/mcporter.json (override with --config <path> or MCPORTER_CONFIG).

Config supports JSONC (comments, trailing commas). Manage via CLI:

npx mcporter config add <name> <url>              # Add HTTP server
npx mcporter config add <name> --command "npx ..." # Add stdio server
npx mcporter config remove <name>                 # Remove server
npx mcporter config import <kind> --copy          # Import from editors

Env var interpolation in config: ${VAR}, ${VAR:-fallback}, $env:VAR. Secrets in headers, env, bearerTokenEnv resolve lazily at runtime.

Calling Tools

Syntax

npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'  # Colon
npx mcporter call linear.create_comment issueId=ENG-123 body='Looks good!'  # Equals
npx mcporter call 'linear.create_issue(title: "Bug", team: "ENG")'          # Function
npx mcporter linear.list_issues                                              # Shorthand
npx mcporter call https://mcp.linear.app/mcp.list_issues                     # Full URL
npx mcporter call --stdio "bun run ./server.ts" scrape url=https://example.com  # Stdio
npx mcporter call <server>.<tool> --args '{"key": "value"}'                  # JSON

Key Flags

| Flag | Purpose | |------|---------| | --output json | Machine-readable output | | --config <path> | Custom config file | | --json | JSON output for list, auth | | --schema | Full tool schema for list | | --all-parameters | Show all optional params | | --no-browser | Headless OAuth | | --persist <file> | Save ad-hoc server to config | | -- | Stop flag parsing |

Auth

npx mcporter auth <server>              # Browser OAuth
npx mcporter auth <server> --no-browser # Headless (prints URL)

Ad-hoc Servers

Call any MCP server without editing config:

npx mcporter list --http-url https://mcp.example.com/mcp --name my-server
npx mcporter call --stdio "npx -y some-mcp-server" tool_name arg=value

Add --persist config/mcporter.json to save for reuse.

Daemon

Keep stateful servers alive between calls:

npx mcporter daemon start|status|stop|restart

Add "lifecycle": "keep-alive" to a server config entry.

Code Generation

Read references/codegen.md for CLI generation, TypeScript types, and runtime API.

Gotchas

• Tool names auto-correct from typos (listIssues → list_issues)
• Skip the verb: npx mcporter firecrawl runs list firecrawl automatically
• Dotted tokens dispatch to call: npx mcporter linear.list_issues
• -- stops flag parsing for positional values starting with --
• OAuth requires a browser by default; use --no-browser for headless
• Stdio servers inherit shell environment; use --env KEY=val only for overrides
• Config resolution order: --config > MCPORTER_CONFIG > ./config/mcporter.json > ~/.config/mcporter/mcporter.json
• Secrets (Authorization, env) resolve at runtime, not at parse time