interactive

You run the interactive MCP server locally to enable real-time interaction between a large language model and you, the user. This server lets the model ask you questions, display OS notifications, and start or manage persistent or focused chat sessions right on your machine, making interactive workflows more natural and efficient.

How to use

Start by configuring your MCP client to load the interactive MCP server. Once running, you can use the provided tools to ask you questions, trigger notifications, and manage intensive chat sessions. Use the tools frequently to gather user input, confirm actions, and present predefined options to streamline decisions. Always ask clarifying questions before acting when requirements are unsure, and confirm plans for significant actions before proceeding.

How to install

Prerequisites: ensure you have Node.js installed on your system and the npx command available. You will also need pnpm for development workflows.

Install dependencies and set up the project for development.

# Install dependencies
pnpm install

# Start the application in development mode
pnpm start

Configuration and usage notes

You configure client integration by providing a minimal MCP configuration that points to the interactive MCP server. You can customize options such as the input timeout and which tools are enabled by adding command-line flags to the args array in your client setup.

Examples include enabling a basic run, using a specific version, or adjusting the timeout. See the code blocks for concrete configurations you can copy and adapt in your client.

{
  "mcpServers": {
    "interactive": {
      "command": "npx",
      "args": ["-y", "interactive-mcp"]
    }
  }
}

Troubleshooting tips

If prompts time out, increase the timeout value you pass to the server. If you want to disable certain tools, provide a comma-separated list to the disable-tools option. Check that your MCP client is using the correct command and arguments and that Node.js is available on your system.

Notes on macOS and terminal behavior

On macOS you can adjust Terminal.app profile settings to ensure the terminal window closes gracefully when the MCP server starts and stops, improving the overall user experience during interactive sessions.

Development setup and tooling

If you are contributing or modifying the server, you will work with Node.js and pnpm. The project is written in TypeScript and designed to run alongside MCP clients on your local machine.

Available tools

request_user_input

Ask the user a question and capture their answer, with optional predefined choices.

message_complete_notification

Send a simple OS notification when a message completes.

start_intensive_chat

Start a persistent command-line chat session that remains active across prompts.

ask_intensive_chat

Ask a question within an active intensive chat session.

stop_intensive_chat

Close an active intensive chat session.