\n\nMCPorter 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.\n\n## Install\n\nTry the CLI without installing it:\n\n```sh\nnpx mcporter --version\n```\n\nInstall it for repeated command-line use:\n\n```sh\nbrew install steipete/tap/mcporter\n# or\nnpm install -g mcporter\n```\n\nNode 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](docs/install.md).\n\n## Quick start\n\nInspect a public MCP server, then call one of its tools:\n\n```sh\nnpx mcporter list https://mcp.context7.com/mcp --brief\nnpx mcporter call https://mcp.context7.com/mcp.resolve-library-id \\\n query=\"React hooks docs\" libraryName=react\n```\n\nThe 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](docs/quickstart.md) for resources, generated CLIs, and typed clients.\n\n## Core workflows\n\n| Goal | Command or API | Details |\n| ----------------------------------------- | ------------------------------------ | ------------------------------------------ |\n| Discover servers and tools | `mcporter list` | [CLI reference](docs/cli-reference.md) |\n| Call tools and read resources | `mcporter call`, `mcporter resource` | [Call syntax](docs/call-syntax.md) |\n| Connect to a one-off URL or stdio command | `--http-url`, `--stdio` | [Ad-hoc servers](docs/adhoc.md) |\n| Complete or seed OAuth | `mcporter auth`, `mcporter vault` | [Configuration](docs/config.md) |\n| Generate a focused CLI | `mcporter generate-cli` | [CLI generator](docs/cli-generator.md) |\n| Generate TypeScript types or clients | `mcporter emit-ts` | [Typed clients](docs/emit-ts.md) |\n| Capture a reproducible MCP session | `mcporter record`, `mcporter replay` | [Record and replay](docs/record-replay.md) |\n\nHuman-readable output goes to stdout by default. Use JSON output when another program or agent needs a stable result, and consult `mcporter --help` for the flags supported by that command.\n\n## Configuration and discovery\n\nMCPorter 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:\n\n```json\n{\n \"mcpServers\": {\n \"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\"\n }\n }\n}\n```\n\nConfig 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](docs/config.md) defines precedence and the full schema; the [import reference](docs/import.md) 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.\n\nChrome DevTools definitions using `--autoConnect` can control Chrome through a paired [OpenClaw extension relay](docs/daemon.md#chrome-devtools-through-the-openclaw-extension-relay). MCPorter discovers OpenClaw's active extension relay endpoint, while preserving an explicit `MCPORTER_CHROME_DEVTOOLS_RELAY_URL` override and the legacy `127.0.0.1:18799` fallback. 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. Routing defaults to `prefer`, which may fall back only to Chrome's original auto-connect path; `require` fails closed and `off` keeps original auto-connect.\n\n## TypeScript runtime\n\nUse `createRuntime()` when a process needs explicit server definitions, connection reuse, or several calls:\n\n```ts\nimport { createRuntime } from 'mcporter';\n\nconst runtime = await createRuntime({\n servers: [{ name: 'context7', command: { kind: 'http', url: new URL('https://mcp.context7.com/mcp') } }],\n});\ntry {\n console.log((await runtime.listTools('context7')).map((tool) => tool.name));\n} finally {\n await runtime.close();\n}\n```\n\n`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](docs/mcp.md) and [tool-calling guide](docs/tool-calling.md).\n\n## Protocols and long-lived servers\n\nMCPorter 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.\n\nThe 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](docs/protocols.md) for negotiation controls and [the keep-alive daemon](docs/daemon.md) for pooled servers, the MCP bridge, and Chrome DevTools integration.\n\n## Development\n\n```sh\npnpm install --frozen-lockfile\npnpm check\npnpm test\npnpm docs:site\n```\n\nThe project uses the Node and pnpm versions declared in `package.json`. Live hosted-server tests are opt-in; see [live tests](docs/livetests.md) and [manual testing](docs/manual-testing.md).\n\n## Related\n\n- [CodexBar](https://codexbar.app) keeps Codex token windows visible in the macOS menu bar.\n- [Trimmy](https://trimmy.app) flattens multi-line shell snippets for one-shot pasting.\n- [Oracle](https://github.com/steipete/oracle) bundles prompts and files for multi-model runs.\n- [Model Context Protocol specification](https://github.com/modelcontextprotocol/specification).\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","readmeFilename":"README.md"}
![\"MCPorter](\"mcporter.png\")
\n