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






<p align="center">

<img src="mcporter.png" alt="MCPorter header banner" width="1100">

</p>

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 |

| 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.

Protocols and long-lived servers

MCPorter connects to stdio, Streamable HTTP, and legacy SSE servers. It negotiates the current 2026-07-28 protocol or a legacy revision per server, while legacy connections advertise client elicitation capabilities. Interactive CLI calls can answer form and URL requests; headless and daemon-managed calls decline them with an actionable hint.

The repository's modern and legacy fixture servers cover both generations; CI exercises representative fixture paths end-to-end over stdio and Streamable HTTP. See protocols and interactive requests for negotiation controls and the keep-alive daemon for pooled servers, the MCP bridge, and Chrome DevTools integration.

Development

pnpm install --frozen-lockfile
pnpm check
pnpm test
pnpm docs:site

The project uses the pnpm version declared in package.json and Vitest 5. Use Node 24 or 26 for development: CI checks Node 24 on Linux, macOS, and Windows, plus Node 26 on Linux. Vitest 5 excludes the non-LTS Node 25 line; the package's runtime requirement remains Node 24 or newer. Live hosted-server tests are opt-in; see live tests and manual testing.

Related

• CodexBar keeps Codex token windows visible in the macOS menu bar.
• Trimmy flattens multi-line shell snippets for one-shot pasting.
• Oracle bundles prompts and files for multi-model runs.
• Model Context Protocol specification.

License

MIT — see LICENSE.