Skip to content
Back to search

interactive-mcp

Vibe coding should have human in the loop! interactive-mcp: Local, cross-platform MCP server for interact with your AI Agent

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ttommyth--interactive-mcp/badge.svg)](/listings/ttommyth--interactive-mcp)

HTML

<a href="/listings/ttommyth--interactive-mcp"><img src="/api/listings/ttommyth--interactive-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

This section is primarily for developers looking to modify or contribute to the server. If you just want to _use_ the server with an MCP client, see the "Client Configuration" section above.

Prerequisites

- **Node.js:** Check `package.json` for version compatibility. - **pnpm:** Used for package management. Install via `npm install -g pnpm` after installing Node.js.

Installation (Developers)

1. Clone the repository:

   git clone https://github.com/ttommyth/interactive-mcp.git
   cd interactive-mcp

2. Install dependencies:

   pnpm install

Running the Application (Developers)

pnpm start

Command-Line Options

The `interactive-mcp` server accepts the following command-line options. These should typically be configured in your MCP client's JSON settings by adding them directly to the `args` array (see "Client Configuration" examples).

| Option | Alias | Description | | ----------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--timeout` | `-t` | Sets the default timeout (in seconds) for user input prompts. Defaults to 30 seconds. | | `--disable-tools` | `-d` | Disables specific tools or groups (comma-separated list). Prevents the server from advertising or registering them. Options: `request_user_input`, `message_complete_notification`, `intensive_chat`. |

**Example:** Setting multiple options in the client config `args` array:

// Example combining options in client config's "args":
"args": [
  "-y", "interactive-mcp",
  "-t", "30", // Set timeout to 30 seconds
  "--disable-tools", "message_complete_notification,intensive_chat" // Disable notifications and intensive chat
]

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 211 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # interactive-mcp
  2. [![npm version](https://img.shields.io/npm/v/interactive-mcp)](https://www.npmjs.com/package/interactive-mcp) [![npm downloads](https://img.shields.io/npm/dm/interactive-mcp)](https://www.npmjs.com/package/interactive-mcp) [![smithery badge](https://smithery.ai/badge/@ttommyth/interactive-mcp)](https://smithery.ai/server/@ttommyth/interactive-mcp) [![GitHub license](https://img.shields.io/github/license/ttommyth/interactive-mcp)](https://github.com/ttommyth/interactive-mcp/blob/main/LICENSE) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier) [![Platforms](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-blue)](https://github.com/ttommyth/interactive-mcp) [![GitHub last commit](https://img.shields.io/github/last-commit/ttommyth/interactive-mcp)](https://github.com/ttommyth/interactive-mcp/commits/main)
  3. [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=interactive&config=eyJjb21tYW5kIjoibnB4IC15IGludGVyYWN0aXZlLW1jcCJ9)
  4. ![Screenshot 2025-05-13 213745](https://github.com/user-attachments/assets/40208534-5910-4eb2-bfbc-58f7d93aec95)
  5. A MCP Server implemented in Node.js/TypeScript, facilitating interactive communication between LLMs and users. **Note:** This server is designed to run locally alongside the MCP client (e.g., Claude Desktop, VS Code), as it needs direct access to the user's operating system to display notifications and command-line prompts.
  6. _(Note: This project is in its early stages.)_
  7. **Want a quick overview?** Check out the introductory blog post: [Stop Your AI Assistant From Guessing — Introducing interactive-mcp](https://medium.com/@ttommyth/stop-your-ai-assistant-from-guessing-introducing-interactive-mcp-b42ac6d9b0e2)
  8. [Demo Video](https://youtu.be/ebwDZdfgSHo)
  9. <div align="center">
  10. <a href="https://glama.ai/mcp/servers/@ttommyth/interactive-mcp">
  11. <img width="380" height="200" src="https://glama.ai/mcp/servers/@ttommyth/interactive-mcp/badge" alt="interactive-mcp MCP server" />
  12. </a>
  13. </div>
  14. ## Tools
  15. This server exposes the following tools via the Model Context Protocol (MCP):
  16. - `request_user_input`: Asks the user a question and returns their answer. Can display predefined options.
  17. - `message_complete_notification`: Sends a simple OS notification.
  18. - `start_intensive_chat`: Initiates a persistent command-line chat session.
  19. - `ask_intensive_chat`: Asks a question within an active intensive chat session.
  20. - `stop_intensive_chat`: Closes an active intensive chat session.
  21. ## Demo
  22. Here are demonstrations of the interactive features:
  23. | Normal Question | Completion Notification |
  24. | :--------------------------------------------------------: | :-----------------------------------------------------------------: |
  25. | ![Normal Question Demo](./docs/assets/normal-question.gif) | ![Completion Notification Demo](./docs/assets/end-notification.gif) |
  26. | Intensive Chat Start | Intensive Chat End |
  27. | :------------------------------------------------------------------: | :--------------------------------------------------------------: |
  28. | ![Start Intensive Chat Demo](./docs/assets/start-intensive-chat.gif) | ![End Intensive Chat Demo](./docs/assets/end-intensive-chat.gif) |
  29. ## Usage Scenarios
  30. This server is ideal for scenarios where an LLM needs to interact directly with the user on their local machine, such as:
  31. - Interactive setup or configuration processes.
  32. - Gathering feedback during code generation or modification.
  33. - Clarifying instructions or confirming actions in pair programming.
  34. - Any workflow requiring user input or confirmation during LLM operation.
  35. ## Client Configuration
  36. This section explains how to configure MCP clients to use the `interactive-mcp` server.
  37. By default, user prompts will time out after 30 seconds. You can customize server options like timeout or disabled tools by adding command-line flags directly to the `args` array when configuring your client.
  38. Please make sure you have the `npx` command available.
  39. ### Usage with Claude Desktop / Cursor
  40. Add the following minimal configuration to your `claude_desktop_config.json` (Claude Desktop) or `mcp.json` (Cursor):
  41. ```json
  42. {
  43. "mcpServers": {
  44. "interactive": {
  45. "command": "npx",
  46. "args": ["-y", "interactive-mcp"]
  47. }
  48. }
  49. }
  50. ```
  51. **With specific version**
  52. ```json
  53. {
  54. "mcpServers": {
  55. "interactive": {
  56. "command": "npx",
  57. "args": ["-y", "interactive-mcp@1.9.0"]
  58. }
  59. }
  60. }
  61. ```
  62. **Example with Custom Timeout (30s):**
  63. ```json
  64. {
  65. "mcpServers": {
  66. "interactive": {
  67. "command": "npx",
  68. "args": ["-y", "interactive-mcp", "-t", "30"]
  69. }
  70. }
  71. }
  72. ```
  73. ### Usage with VS Code
  74. Add the following minimal configuration to your User Settings (JSON) file or `.vscode/mcp.json`:
  75. ```json
  76. {
  77. "mcp": {
  78. "servers": {
  79. "interactive-mcp": {
  80. "command": "npx",
  81. "args": ["-y", "interactive-mcp"]
  82. }
  83. }
  84. }
  85. }
  86. ```
  87. #### macOS Recommendations
  88. For a smoother experience on macOS using the default `Terminal.app`, consider this profile setting:
  89. - **(Shell Tab):** Under **"When the shell exits"** (**Terminal > Settings > Profiles > _[Your Profile]_ > Shell**), select **"Close if the shell exited cleanly"** or **"Close the window"**. This helps manage windows when the MCP server starts and stops.
  90. ## Development Setup
  91. This section is primarily for developers looking to modify or contribute to the server. If you just want to _use_ the server with an MCP client, see the "Client Configuration" section above.
  92. ### Prerequisites
  93. - **Node.js:** Check `package.json` for version compatibility.
  94. - **pnpm:** Used for package management. Install via `npm install -g pnpm` after installing Node.js.
  95. ### Installation (Developers)
  96. 1. Clone the repository:
  97. ```bash
  98. git clone https://github.com/ttommyth/interactive-mcp.git
  99. cd interactive-mcp
  100. ```
  101. 2. Install dependencies:
  102. ```bash
  103. pnpm install
  104. ```
  105. ### Running the Application (Developers)
  106. ```bash
  107. pnpm start
  108. ```
  109. #### Command-Line Options
  110. The `interactive-mcp` server accepts the following command-line options. These should typically be configured in your MCP client's JSON settings by adding them directly to the `args` array (see "Client Configuration" examples).
  111. | Option | Alias | Description |
  112. | ----------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  113. | `--timeout` | `-t` | Sets the default timeout (in seconds) for user input prompts. Defaults to 30 seconds. |
  114. | `--disable-tools` | `-d` | Disables specific tools or groups (comma-separated list). Prevents the server from advertising or registering them. Options: `request_user_input`, `message_complete_notification`, `intensive_chat`. |
  115. **Example:** Setting multiple options in the client config `args` array:
  116. ```jsonc
  117. // Example combining options in client config's "args":
  118. "args": [
  119. "-y", "interactive-mcp",
  120. "-t", "30", // Set timeout to 30 seconds
  121. "--disable-tools", "message_complete_notification,intensive_chat" // Disable notifications and intensive chat
  122. ]
  123. ```
  124. ## Development Commands
  125. - **Build:** `pnpm build`
  126. - **Lint:** `pnpm lint`
  127. - **Format:** `pnpm format`
  128. ## Guiding Principles for Interaction
  129. When interacting with this MCP server (e.g., as an LLM client), please adhere to the following principles to ensure clarity and reduce unexpected changes:
  130. - **Prioritize Interaction:** Utilize the provided MCP tools (`request_user_input`, `start_intensive_chat`, etc.) frequently to engage with the user.
  131. - **Seek Clarification:** If requirements, instructions, or context are unclear, **always** ask clarifying questions before proceeding. Do not make assumptions.
  132. - **Confirm Actions:** Before performing significant actions (like modifying files, running complex commands, or making architectural decisions), confirm the plan with the user.
  133. - **Provide Options:** Whenever possible, present the user with predefined options through the MCP tools to facilitate quick decisions.
  134. You can provide these instructions to an LLM client like this:
  135. ```markdown
  136. # Interaction
  137. - Please use the interactive MCP tools
  138. - Please provide options to interactive MCP if possible
  139. # Reduce Unexpected Changes
  140. - Do not make assumption.
  141. - Ask more questions before executing, until you think the requirement is clear enough.
  142. ```
  143. ## Contributing
  144. Contributions are welcome! Please follow standard development practices. (Further details can be added later).
  145. ## License
  146. MIT (See `LICENSE` file for details - if applicable, or specify license directly).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.