Model Context Protocol

MCP Integration

Connect AI agents to your activity data via the Model Context Protocol. Stubble runs a local MCP server that lets Claude Code, OpenClaw, and other compatible tools query your timeline, projects, and work patterns—securely and privately.

Getting Started

Quick Start

1

Retrieve your API key

Run this command to display your MCP authentication key:

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

Configure your agent

Add Stubble to your MCP configuration.

Claude Code ~/.claude/mcp.json 
{
  "mcpServers": {
    "stubble": {
      "command": "/Applications/Stubble.app/Contents/MacOS/stubble-mcp",
      "env": {
        "STUBBLE_MCP_KEY": "sk-stubble-your-key-here"
      }
    }
  }
}
OpenClaw Settings → MCP Servers 
{
  "stubble": {
    "command": "/Applications/Stubble.app/Contents/MacOS/stubble-mcp",
    "env": {
      "STUBBLE_MCP_KEY": "sk-stubble-your-key-here"
    }
  }
}
3

Start using

Ask your AI agent about your work:

"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?"
Capabilities

Available Tools

The Stubble MCP server exposes these tools to connected agents:

query_tasks

AI-generated task summaries with duration, apps used, and context.

get_activity_log

Raw activity records including app switches and window titles.

search_activities

Full-text search across your activity history.

get_projects

Project summaries with total time, recent activity, and status.

get_timeline

Day view with task blocks and idle periods.

get_day_summary

AI-generated daily summary with focus metrics and highlights.

get_user_profile

Your role, active projects, and tech stack for context.

get_ocr_digest

Extracted URLs, file paths, and text from screen captures.

Response Format

Example Response

Here's what a typical query_tasks response looks like:

{
  "tasks": [
    {
      "title": "Working on authentication flow",
      "description": "Implementing OAuth2 login with Google provider",
      "start": "2024-01-15T09:30:00Z",
      "end": "2024-01-15T11:45:00Z",
      "duration_minutes": 135,
      "apps": ["VS Code", "Terminal", "Chrome"],
      "websites": ["github.com", "developers.google.com"],
      "project": "stubble-app"
    }
  ]
}
Privacy First

Security & Privacy

Authentication

All requests require a valid STUBBLE_MCP_KEY in the environment. Keys are stored locally and never transmitted.

Rate Limiting

60 requests per minute per client. Helps prevent runaway agents from overwhelming the system.

Data Sanitization

Automatic redaction of sensitive patterns: JWT tokens, API keys, passwords, and email addresses.

What's Never Exposed

Screenshots, meeting notes, full file paths, complete URLs with query parameters.

Audit Logging

All MCP requests are logged to ~/.stubble/mcp-audit.log for review.

Key Rotation

Rotate your key anytime with stubble-mcp --rotate-key

Support

Troubleshooting

"Authorization failed" error

Verify your key is correct by running stubble-mcp --show-key and comparing it to your config.

"Rate limit exceeded" error

Wait 60 seconds before retrying. Consider batching queries or reducing polling frequency.

Empty results

Make sure Stubble is running and has recorded activity. Check that the time range in your query matches when you were active.

Connection refused

Verify the MCP server is running: pgrep -f stubble-mcp. Restart Stubble if needed.

Ready to connect your AI?

Download Stubble and start giving your AI agents the context they need.

Download for Mac