Claude Runner - MCP Server with Job Scheduling

A single-file MCP server that schedules and executes Claude Code CLI tasks via cron expressions. Features a web dashboard, webhook support, dynamic MCP server creation, and token/cost tracking.

Prerequisites

• Python 3.11+ (required for asyncio.timeout())
• Claude Agent SDK (pip install claude-agent-sdk)
• SQLite3 (usually pre-installed on macOS/Linux)

Quick Start

# Clone the repository
git clone https://github.com/floriansmeyers/SFLOW-AIRunner-MCP-PRD.git
cd SFLOW-AIRunner-MCP-PRD

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the server (stdio transport for Claude Desktop)
python server.py

On first run, the server will:

1. Create jobs.db SQLite database with all tables
2. Auto-generate OAuth credentials (printed to stderr - save these!)
3. Start the scheduler loop (checks every 60 seconds)

Running

Local (stdio transport - for Claude Desktop)

python server.py

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "claude-runner": {
      "command": "/path/to/SFLOW-AIagents-MCP-Spinner/.venv/bin/python",
      "args": ["/path/to/SFLOW-AIagents-MCP-Spinner/server.py"]
    }
  }
}

Important: Use the full path to the Python interpreter inside your .venv to ensure dependencies are available.

Remote (SSE transport - for web dashboard)

MCP_TRANSPORT=sse python server.py
# Server accessible at http://localhost:8080
# Web dashboard at http://localhost:8080/

Both Transports

MCP_TRANSPORT=both python server.py
# stdio for Claude Desktop + SSE for web dashboard

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | MCP_TRANSPORT | No | both | Transport mode: stdio, sse, or both | | OAUTH_CLIENT_ID | No | auto-generated | OAuth client ID | | OAUTH_CLIENT_SECRET | No | auto-generated | OAuth client secret | | OAUTH_SECRET_KEY | No | auto-generated | Secret key for signing JWT tokens | | DASHBOARD_USERNAME | No | - | Basic auth username for dashboard | | DASHBOARD_PASSWORD | No | - | Basic auth password for dashboard | | NGROK_AUTHTOKEN | No | - | ngrok auth token for remote tunneling | | PUBLIC_URL | No | - | Override base URL for OAuth callbacks (e.g., https://your-domain.com) |

Create a .env file to persist these:

OAUTH_CLIENT_ID=your_client_id
OAUTH_CLIENT_SECRET=your_client_secret
OAUTH_SECRET_KEY=your_secret_key
DASHBOARD_USERNAME=admin
DASHBOARD_PASSWORD=secure_password
NGROK_AUTHTOKEN=your_ngrok_token

Authentication (OAuth 2.1)

SSE transport requires OAuth 2.1 authentication. On first startup, the server auto-generates credentials and prints them to stderr:

============================================================
OAUTH CREDENTIALS FOR CLAUDE CONNECTOR
============================================================
Client ID:     abc123...
Client Secret: xyz789...

Save these to your .env file:
  OAUTH_CLIENT_ID=abc123...
  OAUTH_CLIENT_SECRET=xyz789...
============================================================

Important: Save these credentials immediately. The secret is only shown once and cannot be recovered.

OAuth Endpoints

| Endpoint | Description | |----------|-------------| | /.well-known/oauth-authorization-server | Server metadata | | /.well-known/oauth-protected-resource | Protected resource metadata | | /oauth/authorize | Authorization endpoint | | /oauth/token | Token endpoint |

Regenerating Credentials

If you lose your credentials, delete the client from the database:

sqlite3 jobs.db "DELETE FROM oauth_clients WHERE client_name = 'Claude (auto)'"

Then restart the server to generate new credentials.

Directory Structure

SFLOW-AIRunner-MCP-PRD/
├── server.py              # Main MCP server
├── requirements.txt       # Python dependencies
├── jobs.db               # SQLite database (auto-created)
├── .env                  # Environment variables (optional)
├── fixed-servers/        # Built-in MCP servers
│   └── email/
│       ├── server.py
│       └── metadata.json
├── dynamic_servers/      # User-created MCP servers (auto-created)
│   ├── cat-facts/
│   └── r2-images/
├── deploy/               # Deployment configs (systemd, nginx, deploy script)
│   ├── deploy.sh
│   ├── mcpserver.service
│   ├── nginx.conf
│   └── README-HETZNER.md
└── claude_playground/    # Working directory for job execution (auto-created)

Database

SQLite database at ./jobs.db with the following tables:

Tables

| Table | Description | |-------|-------------| | jobs | Scheduled tasks with cron expressions | | runs | Execution history with output, tokens, cost | | settings | Configuration (allowed tools, MCP servers, credentials) | | webhooks | HTTP endpoints that trigger prompts | | oauth_clients | OAuth client credentials | | oauth_codes | OAuth authorization codes | | oauth_refresh_tokens | OAuth refresh tokens |

Default Settings

On first run, these defaults are created:

| Key | Default Value | |-----|---------------| | allowed_tools | ["WebSearch", "WebFetch", "Read", "Write", "Edit", "Bash"] | | mcp_servers | [] | | mcp_env_vars | {} | | webhook_base_url | "http://localhost:8080" | | sandbox_mode | true |

Clean Reset

To completely reset the database:

rm jobs.db
python server.py  # Creates fresh database

MCP Tools Available

Job Management

| Tool | Description | |------|-------------| | list_jobs | List all scheduled jobs | | get_job(job_id) | Get a specific job | | create_job(name, cron, prompt, ...) | Create a new scheduled job | | update_job(job_id, ...) | Update an existing job | | delete_job(job_id) | Delete a job and its runs | | trigger_job(job_id) | Manually trigger a job now |

Run Management

| Tool | Description | |------|-------------| | list_runs(job_id?, limit?) | List recent runs | | get_run(run_id) | Get full run details including output | | kill_run(run_id) | Cancel a pending/running run |

Webhooks

| Tool | Description | |------|-------------| | create_webhook(name, prompt_template) | Create a webhook endpoint | | list_webhooks | List all webhooks | | get_webhook(webhook_id) | Get webhook details | | update_webhook(webhook_id, ...) | Update a webhook | | delete_webhook(webhook_id) | Delete a webhook |

Dynamic MCP Servers

| Tool | Description | |------|-------------| | create_mcp_server(name, code, ...) | Create a custom MCP server | | list_dynamic_mcp_servers | List user-created servers | | get_dynamic_mcp_server(name) | Get server details | | update_mcp_server(name, code, ...) | Update a dynamic server's code/description | | delete_mcp_server(name) | Delete a dynamic server | | enable_mcp_server(name) | Enable a dynamic MCP server | | disable_mcp_server(name) | Disable a dynamic MCP server |

Fixed MCP Servers

| Tool | Description | |------|-------------| | list_fixed_mcp_servers | List built-in servers | | enable_fixed_server(name) | Enable a fixed server | | disable_fixed_server(name) | Disable a fixed server |

Internal MCP Tools

| Tool | Description | |------|-------------| | invoke_internal_mcp_tool(tool, payload) | Invoke a tool on an internal MCP server |

Credentials

| Tool | Description | |------|-------------| | set_server_credential(server, key, value) | Set a credential | | get_server_credentials(server) | View credentials (masked) | | list_required_credentials(server) | See required credentials | | get_unconfigured_servers | Find servers missing credentials | | delete_server_credential(server, key) | Delete a credential |

Usage via claude.ai

Once connected, you interact with the server entirely through natural language. Claude translates your requests into the appropriate MCP tool calls behind the scenes.

Important: Jobs are executed via the Claude Agent SDK, which runs the local Claude Code CLI under the hood. You need Claude Code installed and authenticated (claude must be available on the system PATH and logged in) on the machine running the server.

Below are the main workflows.

Creating Custom Tools

You can ask Claude to build new MCP tool servers on the fly. The server code is saved to dynamic_servers/<name>/ and each server gets a DATA_DIR path variable for local file storage. Environment variables referenced via os.environ.get() or os.getenv() in the code are auto-detected and marked as required credentials.

You: Create a tool that fetches the current weather for a given city using the
     OpenWeatherMap API.

Claude: [calls create_mcp_server — saves server to dynamic_servers/weather/,
         detects OPENWEATHERMAP_API_KEY from code]
  Done! I created the "weather" server with a get_weather(city) tool.
  It needs an API key — want me to store yours now?

You: Yes, the key is abc123

Claude: [calls set_server_credential("weather", "OPENWEATHERMAP_API_KEY", "abc123")]
  Credential saved. The weather server is ready to use.

Scheduling Recurring Jobs

Jobs run on cron schedules using the Claude Agent SDK. You can specify which tools the job is allowed to use (empty array [] means all tools).

You: Create a job that runs every weekday at 9am to summarize our Azure DevOps sprint

Claude: [calls create_job with:]
  name: "Daily Sprint Summary"
  cron: "0 9 * * 1-5"
  prompt: "Connect to Azure DevOps and summarize the current sprint..."
  tools: ["mcp__azure-devops__wit_my_work_items", "mcp__email__send_email"]
  Job created (id: a1b2c3d4). Next run: tomorrow at 9:00 AM.

You: Show me the last 5 runs

Claude: [calls list_runs with limit=5]
  Here are the recent runs — 4 completed successfully, 1 errored out...

Setting Up Webhooks

Webhooks let external services trigger a prompt via HTTP POST. The prompt_template supports {{payload}} for the full body or {{payload.field.subfield}} for nested values.

You: Create a webhook that sends a Slack summary whenever a new Azure DevOps
     work item is created. The POST body will have the item title at
     resource.fields.System.Title.

Claude: [calls create_webhook with:]
  name: "New Work Item Notifier"
  prompt_template: "A new work item was created: {{payload.resource.fields.System.Title}}.
                    Summarize it and post to Slack."
  Webhook created! POST to this URL to trigger it:
  https://your-server.com/webhook/abc123def456...

You: Test it — trigger the webhook manually

Claude: I can't trigger webhooks via MCP, but you can test with curl:
  curl -X POST https://your-server.com/webhook/abc123def456... \
    -H "Content-Type: application/json" \
    -d '{"resource":{"fields":{"System":{"Title":"Bug: login broken"}}}}'

Invoking Tools Directly

Use invoke_internal_mcp_tool to call a tool on any enabled MCP server immediately, without creating a job.

You: Use the weather tool to check the forecast in Berlin

Claude: [calls invoke_internal_mcp_tool with:]
  tool: "mcp__weather__get_weather"
  payload: {"city": "Berlin"}
  Currently 12°C and cloudy in Berlin, with rain expected this afternoon.

Managing Servers & Credentials

You can enable, disable, and update both built-in (fixed) and user-created (dynamic) servers, and manage their credentials.

You: What servers are available?

Claude: [calls list_fixed_mcp_servers and list_dynamic_mcp_servers]
  Fixed servers: email (enabled), playwright (disabled)
  Dynamic servers: weather (enabled), url-shortener (disabled)

You: Enable playwright and disable the weather server

Claude: [calls enable_fixed_server("playwright") and disable_mcp_server("weather")]
  Done — playwright is now enabled and weather is disabled.

You: Which servers are missing credentials?

Claude: [calls get_unconfigured_servers]
  The email server needs SENDGRID_API_KEY and SENDER_EMAIL.

Ad-hoc Prompts

For one-off tasks, use the Quick Run feature in the web dashboard (SSE mode) to execute a prompt immediately without creating a job. From claude.ai, you can also manually trigger any existing job:

You: Run the "Daily Sprint Summary" job right now

Claude: [calls trigger_job("a1b2c3d4")]
  Run queued (run_id: e5f6g7h8). I'll check back for results.

Cron Examples

| Expression | Description | |------------|-------------| | 0 9 * * 1-5 | Weekdays at 9:00 AM | | 0 */2 * * * | Every 2 hours | | 0 9 * * 1 | Mondays at 9:00 AM | | */30 * * * * | Every 30 minutes | | 0 0 1 * * | First day of month at midnight |

Troubleshooting

ModuleNotFoundError: No module named 'dotenv'

Claude Desktop is using system Python instead of your venv. Update your config to use the full venv path:

{
  "command": "/full/path/to/.venv/bin/python",
  "args": ["/full/path/to/server.py"]
}

OAuth credentials lost

Delete the auto-generated client and restart:

sqlite3 jobs.db "DELETE FROM oauth_clients WHERE client_name = 'Claude (auto)'"
python server.py  # New credentials printed to stderr

Jobs not running

1. Check the scheduler is running (look for "Scheduler loop started" in logs)
2. Verify job is enabled: sqlite3 jobs.db "SELECT enabled FROM jobs"
3. Check cron expression is valid
4. Look for errors in runs: sqlite3 jobs.db "SELECT error FROM runs ORDER BY started_at DESC LIMIT 1"

MCP tools not available in jobs

If a job reports "I don't have access to [MCP server] tools", check the tool name format:

Correct format: mcp__<server>__<tool> (double underscores)

• Example: mcp__email__send_email
• Example: mcp__playwright__navigate

Auto-normalized formats: These are automatically converted:

• email:send_email → mcp__email__send_email
• email.send_email → mcp__email__send_email

Tip: Use an empty tools array [] to allow all available tools, or check the response for tool_warnings to see if any tools were normalized.

Server disconnects immediately

Check stderr output for errors. Common causes:

• Missing dependencies (run pip install -r requirements.txt)
• Python version < 3.11
• Database locked by another process

Git "dubious ownership" error

If auto-deploy fails with "fatal: detected dubious ownership in repository":

git config --system --add safe.directory /opt/mcpserver/app

This happens when the repository is owned by a different user than the one running the deploy script.

Playwright browser not found

If Playwright fails with browser not found errors, install Chromium manually:

# Install system dependencies first (as root) - Ubuntu 24.04
apt install -y libnss3 libnspr4 libatk1.0-0t64 libatk-bridge2.0-0t64 libcups2t64 \
  libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 \
  libpango-1.0-0 libcairo2 libasound2t64

# Then install browser (as application user)
su - mcpuser
cd /opt/mcpserver/app
source venv/bin/activate
playwright install chromium

Verify it works:

python -c "from playwright.sync_api import sync_playwright; p = sync_playwright().start(); b = p.chromium.launch(); print('OK'); b.close(); p.stop()"

Architecture

┌─────────────────────────────────────────────────────────────┐
│                       MCP Server                            │
│  ┌───────────┐  ┌───────────────┐  ┌───────────────────┐   │
│  │ Job CRUD  │  │   Scheduler   │  │   Run Processor   │   │
│  │  Tools    │  │  (60s loop)   │  │     (async)       │   │
│  └─────┬─────┘  └───────┬───────┘  └─────────┬─────────┘   │
│        │                │                    │             │
│        └────────────────┼────────────────────┘             │
│                         ▼                                  │
│                ┌────────────────┐                          │
│                │    SQLite      │                          │
│                │   (jobs.db)    │                          │
│                └────────────────┘                          │
│                         │                                  │
│                         ▼                                  │
│                ┌────────────────┐                          │
│                │ Claude Agent   │                          │
│                │     SDK        │                          │
│                └────────────────┘                          │
└─────────────────────────────────────────────────────────────┘

The server runs three concurrent async components:

1. MCP Server - Exposes 25+ tools via FastMCP
2. Scheduler Loop - Checks every 60 seconds for jobs due based on cron
3. Run Processor Loop - Picks up pending runs and executes them

Key Dependencies

• fastmcp - MCP protocol implementation
• claude-agent-sdk - Core execution engine for running jobs
• croniter - Cron expression parsing
• sendgrid, requests - Email provider integrations
• uvicorn - ASGI server for SSE transport
• pyngrok - ngrok tunnel for remote access from claude.ai
• python-dotenv - .env file loading
• PyJWT - JWT token handling for OAuth
• beautifulsoup4 - Web scraping
• boto3 - AWS integration
• playwright - Browser automation