User Steps MCP Server
An MCP (Model Context Protocol) server that provides a user_steps tool for Claude. This tool allows the agent to present step-by-step checklists to users and automatically opens an interactive terminal UI for completion.
Installation
1. Build the packages
cd user-steps-mcp
npm install
npm run build
cd cli
npm install
npm run build
2. Configure Claude Code
Add the MCP server to your Claude Code configuration. Choose one of these methods:
Option A: Project-level config (.mcp.json in your project root):
{
"mcpServers": {
"user-steps": {
"type": "stdio",
"command": "node",
"args": ["/path/to/user-steps-mcp/dist/index.js"]
}
}
}
Option B: Global config (~/.claude.json):
{
"mcpServers": {
"user-steps": {
"type": "stdio",
"command": "node",
"args": ["/path/to/user-steps-mcp/dist/index.js"]
}
}
}
Option C: Via Claude CLI:
claude mcp add user-steps node /path/to/user-steps-mcp/dist/index.js
3. Verify installation
claude mcp list
Usage
When Claude needs the user to perform manual steps, it will call the user_steps tool, which automatically opens a new terminal window with an interactive checklist UI.
The tool blocks and waits until the user completes the steps or cancels the session.
Companion CLI Controls
| Key | Action |
|---|---|
| ↑/↓ | Navigate steps |
| Space/Enter | Toggle step completion |
| s | Toggle skip step |
| f | Add feedback/notes to step |
| c | Cancel session |
Tool Schema
Input
{
title: string; // Title for the step list (max 50 chars)
description?: string; // Context explaining why these steps are needed
steps: [{
id: string; // Unique step identifier
title: string; // Step title (max 100 chars)
description?: string; // Detailed instructions
type?: 'action' | 'verification' | 'acknowledgment' | 'confirmation';
required?: boolean; // Default: true
dependsOn?: string[]; // Step IDs that must complete first
}];
allowPartialCompletion?: boolean; // Default: false
timeoutMs?: number; // Timeout in milliseconds
}
Output
{
sessionId: string;
status: 'completed' | 'cancelled' | 'timeout' | 'partial';
steps: [{
id: string;
status: 'pending' | 'completed' | 'skipped';
completedAt?: string;
notes?: string;
}];
completedCount: number;
totalCount: number;
startedAt: string;
completedAt?: string;
}
Example Tool Call
{
"title": "Deploy to Production",
"description": "Complete these steps to deploy the new release",
"steps": [
{
"id": "backup",
"title": "Create database backup",
"description": "Run: pg_dump -h localhost production > backup.sql",
"type": "action"
},
{
"id": "verify",
"title": "Verify backup exists",
"type": "verification",
"dependsOn": ["backup"]
},
{
"id": "deploy",
"title": "Run deployment script",
"description": "Execute: ./deploy.sh production",
"type": "action",
"dependsOn": ["verify"]
}
]
}
License
MIT