Kaneo Command-Line Interface (CLI) Options: Complete Guide to kaneo-mcp

The kaneo-mcp CLI automatically switches between an interactive installer and an MCP server based on whether stdin is a TTY, while supporting explicit commands like install, serve, and --help.

The Kaneo project provides a lightweight command-line interface through the @kaneo/mcp package, enabling seamless integration with AI coding assistants. Understanding the Kaneo command-line interface (CLI) options is essential for configuring the MCP server in tools like Cursor or Claude. This guide examines the source code implementation in the usekaneo/kaneo repository to explain how the binary handles different execution modes.

CLI Commands and Flags

The kaneo-mcp binary recognizes specific flags and subcommands that control its behavior:

• -h, --help, help: Displays usage information via printMainHelp()
• install or setup: Launches the interactive installer to register the MCP client
• serve, server, stdio, or run: Starts the MCP server using stdio transport
• No arguments with TTY: Defaults to the interactive installer
• No arguments without TTY: Automatically starts the MCP server (pipe mode)

How the CLI Decides: Interactive Installer vs MCP Server

The CLI entry point in packages/mcp/src/cli.ts implements a decision tree that determines whether to launch the installer or start the server.

The Decision Tree Implementation

The runCli() function exported from packages/mcp/src/cli.ts processes process.argv and stdin state to route execution:

export async function runCli(): Promise<void> {
  const argv = process.argv.slice(2);

  // Help
  if (argv[0] === "-h" || argv[0] === "--help" || argv[0] === "help") {
    printMainHelp();
    return;
  }

  // Installer
  if (argv[0] === "install" || argv[0] === "setup") {
    await runInstall(argv.slice(1));
    return;
  }

  // Server (aliases)
  if (argv[0] !== undefined) {
    if (SERVE_ALIASES.has(argv[0])) {
      await startMcpServer();
      return;
    }
    console.error(`Unknown command: ${argv[0]}`);
    printMainHelp();
    process.exitCode = 1;
    return;
  }

  // Default path
  if (input.isTTY) {
    await runInstall([]);
    return;
  }
  await startMcpServer();
}

This logic ensures that explicit commands take precedence, while the TTY check provides a smart default for interactive users versus piped client processes.

Install Command Options

When invoking the installer via kaneo-mcp install, the runInstall function from packages/mcp/src/install/index.ts handles additional flags:

• --path: Specifies a custom installation directory
• --cursor: Configures integration with Cursor IDE
• --claude: Configures integration with Claude desktop

The installer writes a wrapper script that forwards stdio traffic to the MCP server, registering the client with the specified tool.

Server Mode Aliases

The serve command (and its aliases) triggers startMcpServer(), which initializes the Model Context Protocol server. According to the source in packages/mcp/src/server.ts, the createMcpServer function builds a Hono-style server that communicates via StdioServerTransport. This mode activates automatically when stdin is not a TTY, allowing AI clients to spawn the process and communicate over standard pipes.

Usage Examples

Displaying Help Information

View available commands and options:

npx @kaneo/mcp --help

# or

kaneo-mcp help

Running the Interactive Installer

Launch the guided setup to register with Cursor or Claude:

# Explicit command

kaneo-mcp install

# Implicit (when run in terminal without arguments)

kaneo-mcp

Starting the MCP Server

Manually start the server for client integration:

kaneo-mcp serve

# Equivalent aliases:

kaneo-mcp server
kaneo-mcp stdio
kaneo-mcp run

When called from a client program via pipe, the server starts automatically:

echo "request data" | kaneo-mcp

Summary

• The kaneo-mcp CLI supports explicit commands (install, serve, help) and smart defaults based on TTY detection.
• Source logic resides in packages/mcp/src/cli.ts, with installer details in packages/mcp/src/install/index.ts and server implementation in packages/mcp/src/server.ts.
• The installer configures IDE integration via flags like --cursor and --claude.
• The server starts automatically in pipe mode (non-TTY stdin) or via serve aliases.
• Unknown commands trigger error messages and display help text via printMainHelp().

Frequently Asked Questions

What happens if I run kaneo-mcp without any arguments?

Running kaneo-mcp without arguments triggers different behaviors depending on the environment. If stdin is a TTY (interactive terminal), the CLI launches the interactive installer via runInstall(). If stdin is piped from another process (non-TTY), it automatically starts the MCP server using startMcpServer().

How do I integrate kaneo-mcp with Cursor or Claude?

Use the install command with specific flags. Run kaneo-mcp install --cursor to register with Cursor IDE, or kaneo-mcp install --claude for Claude desktop. The installer in packages/mcp/src/install/index.ts writes the necessary wrapper scripts and configuration files to enable stdio communication between the editor and the Kaneo MCP server.

What is the difference between the install and serve commands?

The install command (or setup) runs the interactive installer that configures your development environment and registers the MCP client with your preferred IDE. The serve command (along with aliases server, stdio, run) immediately starts the MCP server process that handles requests over stdio transport, which is used when AI assistants communicate with Kaneo.

Where is the CLI entry point defined in the source code?

The main entry point is the runCli() function exported from packages/mcp/src/cli.ts. This function parses command-line arguments, checks stdin TTY status, and routes to either runInstall() from packages/mcp/src/install/index.ts or startMcpServer() from packages/mcp/src/server.ts. The binary declaration resides in packages/mcp/package.json.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}