MCPorter 🧳 - Call MCPs from TypeScript or as CLI

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 $XDG_CONFIG_HOME/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 server__tool names.
• Headless OAuth. --no-browser, vault seeding, cached-token refresh, and auth: "refreshable_bearer" 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.

Single-server listings now read like a TypeScript header file so you can copy/paste the signature straight into mcporter call:

linear - Hosted Linear MCP; exposes issue search, create, and workflow tooling.
  23 tools · 1654ms · HTTP https://mcp.linear.app/mcp

  /**
   * Create a comment on a specific Linear issue
   * @param issueId The issue ID
   * @param body The content of the comment as Markdown
   * @param parentId? A parent comment ID to reply to
   */
  function create_comment(issueId: string, body: string, parentId?: string);
  // optional (3): notifySubscribers, labelIds, mentionIds

  /**
   * List documents in the user's Linear workspace
   * @param query? An optional search query
   * @param projectId? Filter by project ID
   */
  function list_documents(query?: string, projectId?: string);
  // optional (11): limit, before, after, orderBy, initiativeId, ...

Here’s what that looks like for Vercel when you run npx mcporter list vercel:

vercel - Vercel MCP (requires OAuth).

  /**
   * Search the Vercel documentation.
   * Use this tool to answer any questions about Vercel’s platform, features, and best practices,
   * including:
   * - Core Concepts: Projects, Deployments, Git Integration, Preview Deployments, Environments
   * - Frontend & Frameworks: Next.js, SvelteKit, Nuxt, Astro, Remix, frameworks configuration and
   *   optimization
   * - APIs: REST API, Vercel SDK, Build Output API
   * - Compute: Fluid Compute, Functions, Routing Middleware, Cron Jobs, OG Image Generation, Sandbox,
   *   Data Cache
   * - AI: Vercel AI SDK, AI Gateway, MCP, v0
   * - Performance & Delivery: Edge Network, Caching, CDN, Image Optimization, Headers, Redirects,
   *   Rewrites
   * - Pricing: Plans, Spend Management, Billing
   * - Security: Audit Logs, Firewall, Bot Management, BotID, OIDC, RBAC, Secure Compute, 2FA
   * - Storage: Blog, Edge Config
   *
   * @param topic Topic to focus the documentation search on (e.g., 'routing', 'data-fetching').
   * @param tokens? Maximum number of tokens to include in the result. Default is 2500.
   */
  function search_vercel_documentation(topic: string, tokens?: number);

  /**
   * Deploy the current project to Vercel
   */
  function deploy_to_vercel();

Required parameters always show; optional parameters stay hidden unless (a) there are only one or two of them alongside fewer than four required fields or (b) you pass --all-parameters. Whenever MCPorter hides parameters it prints Optional parameters hidden; run with --all-parameters to view all fields. so you know how to reveal the full signature. Return types are inferred from the tool schema’s title, falling back to omitting the suffix entirely instead of guessing.

Context7: fetch docs (no auth required)

npx mcporter call context7.resolve-library-id query="React hooks docs" libraryName=react
npx mcporter call context7.query-docs libraryId=/reactjs/react.dev query="useEffect cleanup"

Linear: search documentation (requires LINEAR_API_KEY)

LINEAR_API_KEY=sk_linear_example npx mcporter call linear.search_documentation query="automations"

Chrome DevTools: snapshot the current tab

npx mcporter call chrome-devtools.take_snapshot
npx mcporter call 'linear.create_comment(issueId: "LNR-123", body: "Hello world")'
npx mcporter call linear.create_comment issueId=LNR-123 body=@comment.md
npx mcporter call https://mcp.linear.app/mcp.list_issues assignee=me
npx mcporter call shadcn.io/api/mcp.getComponent component=vortex   # protocol optional; defaults to https
npx mcporter call linear.listIssues --tool listIssues   # auto-corrects to list_issues
npx mcporter linear.list_issues                         # shorthand: infers `call`
VERCEL_ACCESS_TOKEN=sk_vercel_example npx mcporter call "npx -y vercel-domains-mcp" domain=answeroverflow.com  # quoted stdio cmd + single-tool inference

Tool calls understand a JavaScript-like call syntax, auto-correct near-miss tool names, and emit richer inline usage hints. See docs/call-syntax.md for the grammar and docs/call-heuristic.md for the auto-correction rules.

Helpful flags:

• --config <path> -- custom config file (defaults to ./config/mcporter.json).
• --root <path> -- working directory for stdio commands.
• --log-level <debug|info|warn|error> -- adjust verbosity (respects MCPORTER_LOG_LEVEL).
• --oauth-timeout <ms> -- shorten/extend the OAuth browser wait; same as MCPORTER_OAUTH_TIMEOUT_MS / MCPORTER_OAUTH_TIMEOUT.
• --tail-log -- stream the last 20 lines of any log files referenced by the tool response.
• --output <format> or --raw -- control formatted output (defaults to pretty-printed auto detection).
• --save-images <dir> (on mcporter call) -- save MCP image content blocks to files in the given directory (opt-in; stdout output shape stays unchanged).
• --raw-strings (on mcporter call) -- keep numeric-looking argument values (for key=value, key:value, and trailing positional values) as strings.
• --no-coerce (on mcporter call) -- keep all key=value and positional values as raw strings (disables bool/null/number/JSON coercion).
• key=@path / --key @path (on mcporter call) -- read a named argument as exact UTF-8 text from a file; use @@ for a literal leading @.
• -- (on mcporter call) -- stop flag parsing so the remaining tokens stay literal positional values, even when they start with --.
• --json (on mcporter list) -- emit JSON summaries/counts instead of text. Multi-server runs report per-server statuses, counts, and connection issues; single-server runs include the full tool metadata.
• --status, --exit-code, --quiet (on mcporter list) -- run concise server health checks through the existing list flow; --quiet suppresses output and exits 1 if anything checked is unhealthy.
• --output json/raw (on mcporter call) -- when a connection fails, MCPorter prints the usual colorized hint and also emits a structured { server, tool, issue } envelope so scripts can handle auth/offline/http errors programmatically.
• --json (on mcporter auth) -- emit the same structured connection envelope whenever OAuth/transport setup fails, instead of throwing an error. With --no-browser, it emits auth-start JSON containing authorizationUrl and redirectUrl.
• --no-browser / --browser none (on mcporter auth or mcporter config login) -- suppress browser launch and print the OAuth authorization URL for headless workflows; MCPORTER_OAUTH_NO_BROWSER=1 / true / yes enables the same behavior.
• --json (on mcporter emit-ts) -- print a JSON summary describing the emitted files (mode + output paths) instead of text logs—handy when generating artifacts inside scripts.
• --all-parameters -- show every schema field when listing a server (default output shows at least five parameters plus a summary of the rest).
• --http-url <https://…> / --stdio "command …" -- describe an ad-hoc MCP server inline. STDIO transports now inherit your current shell environment automatically; add --env KEY=value only when you need to inject/override variables alongside --cwd, --name, or --persist <config.json>. These flags now work with mcporter auth too, so mcporter auth https://mcp.example.com/mcp just works.
• For OAuth-protected servers such as vercel, run npx mcporter auth vercel once to complete login.

Tip: You can skip the verb entirely—mcporter firecrawl automatically runs mcporter list firecrawl, and dotted tokens like mcporter linear.list_issues dispatch to the call command (typo fixes included).

Timeouts default to 30 s; override with MCPORTER_LIST_TIMEOUT or MCPORTER_CALL_TIMEOUT when you expect slow startups. OAuth browser handshakes get a separate 5 minute grace period; pass --oauth-timeout <ms> (or export MCPORTER_OAUTH_TIMEOUT_MS) when you need the CLI to bail out faster while you diagnose stubborn auth f