MCPorter 🧳 — Carry MCP tools into scripts, CLIs, and agents

MCPorter is a TypeScript runtime and command-line tool for discovering and calling Model Context Protocol servers. It is for developers and coding agents that need the same MCP tools from a terminal, a script, or a generated standalone CLI.

Install

Try the CLI without installing it:

npx mcporter --version

Install it for repeated command-line use:

brew install steipete/tap/mcporter
# or
npm install -g mcporter

Node 24 or newer is required for npm installs. For the TypeScript runtime, add mcporter to your project with your package manager. Signed macOS binaries and the other supported install paths are covered in the install guide.

Quick start

Inspect a public MCP server, then call one of its tools:

npx mcporter list https://mcp.context7.com/mcp --brief
npx mcporter call https://mcp.context7.com/mcp.resolve-library-id \
  query="React hooks docs" libraryName=react

The first command prints the server's TypeScript-style tool signatures. The second returns matching Context7 library IDs without requiring local configuration or credentials. See the five-minute quickstart for resources, generated CLIs, and typed clients.

Core workflows

Goal	Command or API	Details
Discover servers and tools	mcporter list	CLI reference
Call tools and read resources	mcporter call, mcporter resource	Call syntax
Connect to a one-off URL or stdio command	--http-url, --stdio	Ad-hoc servers
Complete or seed OAuth	mcporter auth, mcporter vault	Configuration
Encrypt the OAuth vault at rest	MCPORTER_VAULT_PASSWORD	Vault Encryption
Generate a focused CLI	mcporter generate-cli	CLI generator
Generate TypeScript types or clients	mcporter emit-ts	Typed clients
Capture a reproducible MCP session	mcporter record, mcporter replay	Record and replay

Human-readable output goes to stdout by default. Use JSON output when another program or agent needs a stable result, and consult mcporter <command> --help for the flags supported by that command.

Configuration and discovery

MCPorter reads project and user config, then imports MCP servers from Cursor, Claude Code and Desktop, Codex, Windsurf, OpenCode, and VS Code. A minimal config/mcporter.json looks like this:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Config files accept JSONC, environment placeholders (${VAR}, ${VAR:-fallback}, or whole-value $env:VAR), HTTP and stdio definitions, OAuth settings, tool filters, and lifecycle policy. The configuration guide defines precedence and the full schema; the import reference lists every discovered client format. The ${env:VAR} form used by some MCP clients is not supported; mcporter rejects it with the accepted alternatives instead of sending it literally.

Chrome DevTools definitions using --autoConnect can control Chrome through a paired OpenClaw extension relay. MCPorter discovers OpenClaw's active extension relay endpoint, with a 20-second cold-start budget and an optional MCPORTER_CHROME_DEVTOOLS_RELAY_URL in the canonical Chrome definition’s env map. Failed discovery reports its cause without guessing a default port. It uses Browser Relay Authentication v2 over one retained loopback socket, keeps the host key out of the network and child process, and gives chrome-devtools-mcp a credential-free loopback URL plus ephemeral authorization through an OS-protected preload handoff. Old relay authentication is never retried. Under shared ownership, both the default prefer and require fail closed; off requires matching canonical configuration. Caller shell relay controls do not override the daemon’s canonical Chrome configuration.

TypeScript runtime

Use createRuntime() when a process needs explicit server definitions, connection reuse, or several calls:

import { createRuntime } from 'mcporter';

const runtime = await createRuntime({
  servers: [{ name: 'context7', command: { kind: 'http', url: new URL('https://mcp.context7.com/mcp') } }],
});
try {
  console.log((await runtime.listTools('context7')).map((tool) => tool.name));
} finally {
  await runtime.close();
}

callOnce() handles a single configured call and cleanup. createServerProxy() maps MCP tool names to callable camelCase properties and wraps results with text, Markdown, JSON, image, and raw-content helpers. See the runtime overview and tool-calling guide.

This is the beginning of the README. Read the rest at the original. Read the full README ↗