Claude Runner

You run Claude-driven MCP tasks on a schedule with a single-file server that can execute Claude Code CLI tasks, manage webhooks, and track token usage and costs. This MCP Server ties your Claude workflows to cron-based scheduling and a lightweight database for runs and configurations, enabling reliable automation and reporting.

How to use

Operate the server by configuring an MCP client to connect via the local stdio transport. Use the provided server instance to schedule jobs, create webhooks, manage dynamic MCP servers, and monitor runs. Your Claude-enabled workflows will be executed through the Claude Agent SDK, backed by a SQLite database that stores jobs, runs, and credentials.

Key usage patterns include: creating scheduled jobs that run at cron-defined times, triggering runs manually, wiring webhooks to prompt-based actions, and managing credentials for dynamic or fixed MCP servers. You will interact with tools through natural language via Claude, which translates your requests into MCP actions behind the scenes.

How to install

Prerequisites are required before you install and run the MCP Server.

1. Ensure you have Python 3.11 or newer installed.

2. Install the Claude Agent SDK for Python.

3. Ensure SQLite3 is available on your system (usually pre-installed on macOS/Linux).

4. Create and activate a Python virtual environment, then install dependencies and start the server.

Additional sections

Configuration overview: The server supports local stdio transport for Claude Desktop use and a remote SSE transport for web dashboard access. On first run, the server creates an SQLite database at jobs.db, prints OAuth credentials to the terminal, and starts a scheduler loop that checks for due jobs every 60 seconds.

Authentication and credentials: OAuth 2.1 is used for SSE transport. Credentials are auto-generated on startup and shown in the terminal output. Save them to your .env file and restart if needed. The OAuth endpoints include metadata and token endpoints, and you can regenerate credentials by removing the auto-generated client from the database and restarting the server.

Webhooks and dynamic servers: Create webhooks to trigger prompts via HTTP POST, and dynamically create MCP servers whose code is stored under dynamic_servers. Each dynamic server gets a DATA_DIR path for local storage, and environment variables referenced by the server code are treated as required credentials.

Job and run management: Use MCP tools to list, create, update, trigger, and delete jobs. You can view runs, retrieve detailed run output, and kill pending or running tasks. Webhooks support prompts with payload-based templating for flexible integrations.

Troubleshooting tips: If the server cannot start or if dependencies are missing, verify that you are running with Python 3.11+, the virtual environment is active, and the dependencies installed from requirements.txt. If OAuth credentials are lost, delete the auto-generated client and restart to generate new credentials. If a job does not run, confirm the scheduler loop is active and the cron expression is valid, then review the latest run for errors.

Cron examples

Weekdays at 9:00 AM: 0 9 * * 1-5

Every 2 hours: 0 */2 * * *

Mondays at 9:00 AM: 0 9 * * 1

Every 30 minutes: */30 * * * *

First day of month at midnight: 0 0 1 * *

Available tools

list_jobs

List all scheduled jobs with their cron expressions and prompts.

get_job

Retrieve details for a specific job by its identifier.

create_job

Create a new scheduled job with a cron expression, prompt, and allowed tools.

update_job

Update an existing job's configuration, including cron and prompt.

delete_job

Delete a job and its associated runs from the database.

trigger_job

Manually trigger a scheduled job immediately.

list_runs

List recent execution runs, optionally filtered by job.

get_run

Fetch complete details of a specific run, including output and metrics.

kill_run

Cancel a pending or running job execution.

create_webhook

Create a webhook endpoint that triggers a prompt based on POST payloads.

list_webhooks

List all configured webhooks.

get_webhook

Get details for a specific webhook.

update_webhook

Update the configuration of an existing webhook.

delete_webhook

Remove a webhook from the system.

create_mcp_server

Create a new dynamic MCP server with code and metadata.

list_dynamic_mcp_servers

List all user-created dynamic MCP servers.

get_dynamic_mcp_server

Get details for a specific dynamic MCP server.

update_mcp_server

Update the code or description of a dynamic MCP server.

delete_mcp_server

Delete a dynamic MCP server.

enable_mcp_server

Enable a dynamic MCP server for use.

disable_mcp_server

Disable a dynamic MCP server without deleting it.

list_fixed_mcp_servers

List built-in fixed MCP servers.

enable_fixed_server

Enable a fixed MCP server by name.

disable_fixed_server

Disable a fixed MCP server by name.

invoke_internal_mcp_tool

Call a tool on an internal MCP server directly.

set_server_credential

Store a credential for a specific MCP server.

get_server_credentials

View credentials for a server, with sensitive values masked.

list_required_credentials

Show all credentials required by a server.

get_unconfigured_servers

Find servers missing credentials that prevent operation.

delete_server_credential

Remove a stored credential for a server.