mcp-runner

What is mcp-runner?

mcp-runner is a TypeScript SDK and CLI for running MCP (Model Context Protocol) servers. It reads configurations from cline_mcp_settings.json and allows reusable server processes with controlled cleanup, enabling multiple operations using the same server instance.

How to use mcp-runner?

Install via npm install, then use CLI commands (e.g., npm run cli -- list-tools <server-name> or npm run cli -- runserver <server-name> [tool-name] [params] [options]). Alternatively, import runServer and terminateServer in your TypeScript code.

Key features of mcp-runner

• Server process reuse across multiple calls
• Graceful termination with timeout handling
• Automatic server lifecycle management
• TypeScript support
• Error handling and logging
• Single server process at a time (singleton)

Use cases of mcp-runner

• Running MCP servers from the command line
• Integrating MCP server calls into TypeScript projects
• Using mcp-runner from other MCP servers
• Automating tool execution with reusable server instances

FAQ from mcp-runner

Where does mcp-runner read server configurations from?

It reads from cline_mcp_settings.json located in the standard configuration directory.

What happens if no tool name is specified when running a server?

The first available tool is used automatically.

Does mcp-runner support output filtering?

Yes, the --text flag outputs only the text content instead of the full JSON response.

How does mcp-runner manage server processes?

The ServerManager is a singleton that ensures only one server process runs at a time; it handles lifecycle, connection, graceful termination, and cleanup.

Do I need to explicitly stop the server after use?

Yes, call terminateServer() when all operations are complete, or it will be terminated automatically on errors.