mcporter

MCPorter 🧳 - Call MCPs from TypeScript or as CLI

<p align="center" <img src="https://raw.githubusercontent.com/openclaw/mcporter/main/mcporter.png" alt="MCPorter header banner" width="1100" </p

<p align="center" <a href="https://www.npmjs.com/package/mcporter"<img src="https://img.shields.io/npm/v/mcporter?style=for-the-badge&logo=npm&logoColor=white" alt="npm version"</a <a href="https://github.com/openclaw/mcporter/actions/workflows/ci.yml"<img src="https://img.shields.io/github/actions/workflow/status/openclaw/mcporter/ci.yml?branch=main&style=for-the-badge&label=tests" alt="CI Status"</a <a href="https://github.com/openclaw/mcporter"<img src="https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=for-the-badge" alt="Platforms"</a <a href="LICENSE"<img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License"</a </p

TypeScript runtime, CLI, and code-generation toolkit for the Model Context Protocol.

MCPorter helps you lean into the "code execution" workflows highlighted in Anthropic's Code Execution with MCP guidance: discover the MCP servers already configured on your system, call them directly, compose richer automations in TypeScript, and mint single-purpose CLIs when you need to share a tool. All of that works out of the box -- no boilerplate, no schema spelunking.

Key Capabilities

• Zero-config discovery. createRuntime() merges your home config (~/.mcporter/mcporter.json[c], or $XDGCONFIGHOME/mcporter/mcporter.json[c] when set) first, then config/mcporter.json, plus Cursor/Claude/Codex/Windsurf/OpenCode/VS Code imports, expands ${ENV} placeholders, and pools connections so you can reuse transports across multiple calls.
• One-command CLI generation. mcporter generate-cli turns any MCP server definition into a ready-to-run CLI, with optional bundling/compilation and metadata for easy regeneration.
• Typed tool clients. mcporter emit-ts emits .d.ts interfaces or ready-to-run client wrappers so agents/tests can call MCP servers with strong TypeScript types without hand-writing plumbing.
• Friendly composable API. createServerProxy() exposes tools as ergonomic camelCase methods, automatically applies JSON-schema defaults, validates required arguments, and hands back a CallResult with .text(), .markdown(), .json(), .images(), and .content() helpers.
• Record/replay fixtures. mcporter record captures MCP JSON-RPC traffic as NDJSON, and mcporter replay serves the same responses deterministically for offline debugging and redacted repros.
• OAuth and stdio ergonomics. Built-in OAuth caching, log tailing, and stdio wrappers let you work with HTTP, SSE, and stdio transports from the same interface.

• Ad-hoc connections. Point the CLI at any MCP endpoint (HTTP or stdio) without touching config, then persist it later if you want. Hosted MCPs that expect a browser login (Supabase, Vercel, etc.) are auto-detected—just run mcporter auth <url and the CLI promotes the definition to OAuth on the fly. See docs/adhoc.md.

What's New in 0.11.0

• Bridge mode. mcporter serve exposes daemon-managed keep-alive servers as one MCP bridge with readable servertool names.
• Headless OAuth. --no-browser, vault seeding, cached-token refresh, and auth: "refreshablebearer" cover non-interactive deployments.
• HTTP compatibility. httpFetch: "node-http1" keeps providers that reject Node's built-in fetch working.
• Safer writes. Config, OAuth vault, JSON output, and cache metadata writes are serialized/atomic so parallel agents stop stepping on each other.
• Release confidence. 0.11.0 is published on npm and Homebrew, and live/published install smokes are green.

Quick Start

MCPorter auto-discovers the MCP servers you already configured in Cursor, Claude Code/Desktop, Codex, or local overrides. You can try it immediately with npx--no installation required. Need a full command reference (flags, modes, return types)? Check out docs/cli-reference.md.

Call syntax options

# Colon-delimited flags (shell-friendly)
npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'

# Function-call style (matches signatures from `mcporter list`)
npx mcporter call 'linear.create_comment(issueId: "ENG-123", body: "Looks good!")'

# Literal positional values that start with `--`
npx mcporter call server.tool -- --raw-value

List your MCP servers

npx mcporter list
npx mcporter list context7 --schema
npx mcporter list https://mcp.linear.app/mcp --all-parameters
npx mcporter list shadcn.io/api/mcp.getComponents           # URL + tool suffix auto-resolves
npx mcporter list --stdio "bun run ./local-server.ts" --env TOKEN=xyz

• Add --json to emit a machine-readable summary with per-server statuses (auth/offline/http/error counts) and, for single-server runs, the full tool schema payload.
• Add --status for a concise single-server status check without tool docs, --exit-code to fail when any checked server is unhealthy, or --quiet for silent health gates.
• Add --verbose to show every config source that registered the server name (primary first), both in text and JSON list output.

You can now point mcporter list at ad-hoc servers: provide a URL directly or use the new --http-url/--stdio flags (plus --env, --cwd, --name, or --persist) to describe any MCP endpoint. Until you persist that definition, you still need to repeat the same URL/stdio flags for mcporter call—the printed slug only becomes reusable once you merge it into a config via --persist or mcporter config add (use --scope home|project to pick the write target). Follow up with mcporter auth https://… (or the same flag set) to finish OAuth without editing config. Full details live in docs/adhoc.md.