Task Scheduler MCP Server

A cross-platform stdio MCP server that provides AI agents a controlled interface to OS-native task schedulers. Supports Windows (Task Scheduler), Linux (crontab), and macOS (launchd).

Supported Platforms

Note: on_event trigger is Windows-only. On Linux/macOS, use file watching or polling instead.

Related MCP server: cron-mcp

Architecture

The server uses a platform abstraction layer with independent implementations per OS:

src/
├── index.ts                    # MCP server (OS-agnostic)
├── types.ts                    # Shared type definitions
├── xml-builder.ts              # Windows XML generation
└── platform/
    ├── interface.ts            # PlatformScheduler interface
    ├── factory.ts              # OS detection + factory
    ├── paths.ts                # Centralized path management
    ├── logger.ts               # Shared JSON-lines logger
    ├── lock.ts                 # File locking utilities
    ├── triggers.ts             # Trigger normalization
    ├── windows/
    │   ├── scheduler.ts        # Windows Task Scheduler
    │   └── credentials.ts      # Windows Credential Manager
    ├── linux/
    │   └── scheduler.ts        # crontab implementation
    └── macos/
        └── scheduler.ts        # launchd implementation

Directory Structure

All data is stored in ~/.agentic_tasks/ (or ~\.agentic_tasks\ on Windows):

~/.agentic_tasks/
├── tasks/                      # Task definitions (JSON files)
├── logs/                       # JSON-lines logs
│   ├── agentic_tasks.log       # Full log
│   └── {task_name}.log         # Per-task logs
├── config/                     # Configuration
│   └── credentials.json        # Credentials (Linux/macOS)
└── dist/                       # Compiled TypeScript

Prerequisites

All Platforms

• Node.js 18+

Windows

• PowerShell 5.1+

• Administrator privileges (for setup)

Linux

• crontab command

• at command (for once trigger)

macOS

• launchctl command (standard on macOS)

Setup

Windows

Run the setup script as Administrator:

powershell -ExecutionPolicy Bypass -File setup.ps1

The setup script will:

1. Create the agentic_worker local user

2. Enable WinRM for PowerShell remoting

3. Create the \agentic_tasks Task Scheduler folder

4. Set folder permissions

5. Store credentials in Windows Credential Manager

6. Build the MCP server

Linux

chmod +x setup-linux.sh
./setup-linux.sh

macOS

chmod +x setup-macos.sh
./setup-macos.sh

MCP Server Configuration

Add this to your opencode.json:

Windows

{
  "mcpServers": {
    "task-scheduler": {
      "command": "node",
      "args": ["C:\\Users\\<username>\\.agentic_tasks\\dist\\index.js"]
    }
  }
}

Linux/macOS

{
  "mcpServers": {
    "task-scheduler": {
      "command": "node",
      "args": ["/home/<username>/.agentic_tasks/dist/index.js"]
    }
  }
}

Available Tools

create_task

Create a new scheduled task.

Parameters:

• name (required): Task name (no path separators or invalid characters)

• description (optional): Task description

• command (required): Command to execute

• arguments (optional): Command arguments

• working_directory (optional): Working directory for the command

• triggers (required): Array of trigger definitions (see below)

• conditions (optional): Task conditions (idle, ac_power)

• settings (optional): Task settings

• enabled (optional): Whether the task is enabled (default: true)

Trigger Types:

{ "type": "once", "datetime": "2024-12-25T10:00:00" }
{ "type": "daily", "time": "09:00", "interval_days": 1 }
{ "type": "weekly", "time": "09:00", "days_of_week": ["monday", "wednesday", "friday"], "interval_weeks": 1 }
{ "type": "on_logon" }
{ "type": "on_event", "channel": "Application", "id": 1000 }

Example:

{
  "name": "daily_backup",
  "description": "Daily backup task",
  "command": "powershell.exe",
  "arguments": "-File C:\\Scripts\\backup.ps1",
  "triggers": [
    { "type": "daily", "time": "02:00" }
  ]
}

delete_task

Delete a scheduled task.

Parameters:

• name (required): Task name

update_task

Update an existing scheduled task.

Parameters:

• name (required): Task name

• All other parameters from create_task are optional (only specified fields are updated)

list_tasks

List all scheduled tasks.

Parameters: None

get_task

Get detailed information about a specific scheduled task.

Parameters:

• name (required): Task name

get_task_log

Get execution log for a specific task.

Parameters:

• name (required): Task name

• max_events (optional): Maximum number of events to return (default: 50)

• level (optional): Filter by event level: "information", "warning", or "error"

get_full_log

Get execution log for all tasks.

Parameters:

• max_events (optional): Maximum number of events to return (default: 100)

• level (optional): Filter by event level: "information", "warning", or "error"

Testing

The project includes three types of tests:

1. Unit Tests (Vitest)

Test individual functions in isolation:

npm test                    # Run all unit tests
npm run test:watch          # Run tests in watch mode
npm run test:coverage       # Run tests with coverage report

Unit tests cover:

• Trigger conversion (cron, plist, Windows XML)

• Path resolution

• Logger operations

• File locking

• XML builder

2. Integration Tests

Test the full MCP server workflow via stdio JSON-RPC:

Windows

powershell -ExecutionPolicy Bypass -File test_scripts\run_all_tests.ps1

Linux/macOS

./test_scripts/run_tests.sh

Integration tests cover:

• Task creation, update, deletion

• Task listing and retrieval

• Log retrieval

• Error handling

3. Manual Testing with MCP Inspector

The MCP Inspector is an official debugging tool for MCP servers. It provides a web UI for manually testing tools.

Running MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

This opens a web interface at http://localhost:5173 where you can:

1. View Available Tools: See all 7 tools with their schemas

2. Test Tools Manually: Invoke tools with custom parameters

3. Inspect Requests/Responses: View the full JSON-RPC payloads

4. Debug Issues: See error messages and stack traces

Example: Testing create_task

1. Open the MCP Inspector web UI

2. Click on "Tools" tab

3. Select "create_task" from the dropdown

4. Enter parameters:

   {
     "name": "test_manual",
     "command": "cmd.exe",
     "arguments": "/c echo manual test",
     "triggers": [
       { "type": "once", "datetime": "2099-01-01T00:00:00" }
     ]
   }

5. Click "Run Tool"

6. View the response in the right panel

Example: Testing list_tasks

1. Select "list_tasks" from the dropdown

2. Leave parameters empty (no parameters required)

3. Click "Run Tool"

4. View the list of tasks in the response

Troubleshooting with MCP Inspector

If a tool fails:

• Check the "Error" tab for detailed error messages

• Verify the request payload matches the tool schema

• Check server logs in the terminal where you ran the inspector

• Use the "Resources" tab to inspect server state

Running All Tests

To run the complete test suite (unit + integration + error handling):

# Windows
powershell -ExecutionPolicy Bypass -File test_scripts\run_all_tests.ps1

# Linux/macOS
./test_scripts/run_tests.sh

License

MIT