MCP Integration

Connect AI agents to your activity data via the Model Context Protocol.

Stubble includes a local MCP server that allows AI agents like Claude Code, OpenClaw, and other MCP-compatible tools to query your activity data securely.

Quick Start

1. Get Your API Key

/Applications/Stubble.app/Contents/MacOS/stubble-mcp --show-key

2. Configure Your AI Agent

Claude Code — add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "stubble": {
      "command": "/Applications/Stubble.app/Contents/MacOS/stubble-mcp",
      "env": {
        "STUBBLE_MCP_KEY": "sk-stubble-your-key-here"
      }
    }
  }
}

OpenClaw — add to your MCP config:

{
  "stubble": {
    "command": "/Applications/Stubble.app/Contents/MacOS/stubble-mcp",
    "env": {
      "STUBBLE_MCP_KEY": "sk-stubble-your-key-here"
    }
  }
}

3. Start Using

Once connected, your AI agent can query your activity data:

"What did I work on today?"
"How much time did I spend in Terminal this week?"
"Show me my project breakdown"
"What was I doing at 2pm yesterday?"

Available Tools

query_tasks

Get AI-generated task summaries for a date range. Returns title, description, duration, apps used, and links.

get_activity_log

Get raw activity records — app switches, window titles, and idle periods. Supports single-date or multi-day range queries.

search_activities

Full-text search across your activity history by app name, window title, or content.

get_projects

Get project activity summaries with durations and associated tasks.

get_timeline

Get the day view timeline showing tasks interleaved with away/idle periods.

get_day_summary

Get the AI-generated day summary with focus time and meeting stats.

get_user_profile

Get your learned profile — role, projects, tech stack, and interests.

get_ocr_digest

Get the daily OCR digest — extracted URLs, file paths, code symbols from screen captures.

Example Response

Calling query_tasks returns structured JSON:

{
  "tasks": [
    {
      "title": "Implementing MCP server",
      "description": "Building secure local API for AI agents...",
      "start_time": "2026-03-23T09:00:00Z",
      "end_time": "2026-03-23T10:30:00Z",
      "duration_minutes": 90,
      "apps": ["Terminal", "VS Code"],
      "websites": ["github.com", "stackoverflow.com"]
    }
  ],
  "count": 1
}

Security & Privacy

Authentication

Every request requires a valid API key passed via the STUBBLE_MCP_KEY environment variable. Keys are stored at ~/.stubble/mcp-key with owner-only permissions.

# Generate a new key (invalidates existing connections)
stubble-mcp --rotate-key

Rate Limiting

60 requests per minute per connected client. Exceeding the limit returns a rate-limited error.

Data Sanitization

All responses are sanitized before returning. Sensitive patterns are automatically redacted:

Data Type	Replacement
JWT tokens	`[REDACTED_JWT]`
API keys (sk-, ghp_, etc.)	`[REDACTED_KEY]`
Passwords	`[REDACTED_CREDENTIAL]`
Email addresses	`[REDACTED_EMAIL]`

What's Never Exposed

Screenshots — image files are never returned
Meeting notes — Granola meeting data is excluded
Full file paths — only basenames returned
Full URLs — only domains by default

Audit Log

Every tool invocation is logged to ~/.stubble/mcp-audit.log:

[2026-03-23T09:42:52Z] tool=query_tasks params={date:"2026-03-23"} rows=3 duration_ms=6

Troubleshooting

"Unauthorized" Error

Your API key is invalid or not set. Run stubble-mcp --show-key and ensure it matches your agent config.

"Rate limited" Error

You've exceeded 60 requests/minute. Wait a moment and retry.

Empty Results

Check the date parameter (defaults to today)
Ensure Stubble daemon is running and collecting data
Verify the database exists at ~/Library/Application Support/Stubble/stubble.db

Connection Issues

Verify the binary path exists:

ls -la /Applications/Stubble.app/Contents/MacOS/stubble-mcp

Test manually:

echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{}}' | stubble-mcp