Windows Context

Windows Context MCP is a high-performance, native Windows service, Model Context Protocol (MCP) server, and Unified Personal Context Hub connecting Windows desktop activity and Android mobile telemetry directly into conversational AI assistants like Google Gemini, OpenAI ChatGPT, and Claude.

---

🌟 Features & Architecture

• 🗄️ Zero-Dependency SQLite Time-Series (src/db.ts): Built on native node:sqlite for persistent indexed focus sessions, 24-hour hourly distributions, and multi-day range analytics.
• 📱 Unified Cross-Device Hub (src/aggregator.ts): Ingests Android screen time and telemetry via /api/sync, calculating combined multi-device screen time, cross-device top applications, and device fleet health.
• 🔄 Dual Protocol Transports:
  • Streamable HTTP / JSON-RPC 2.0 (src/server.ts): Remote MCP gateway on port 3001 for Google Gemini & ChatGPT Custom GPT Actions.
  • Native STDIO Transport (src/stdio.ts): Standard I/O stream for Claude Desktop, Cursor, and local CLI agents (node dist/index.js --stdio).
• 🪟 Native Win32 API Queries (src/collector.ts): Direct User32 / CIM queries for active window titles, process binaries, CPU delta utilization, RAM usage, user idle detection, and battery telemetry.
• 🧪 Comprehensive Test Suite: 23 automated unit and integration tests across SQLite database, cross-device aggregation, and tool executions (npm test).

---

🛠️ MCP Tools Reference (15 Tools)

Tool Name	Type	Description
get_current_windows_context	Real-time	Full real-time snapshot: active window, screen time, CPU/RAM telemetry, battery.
get_active_window	Real-time	Focused foreground window title, process name, and category.
get_pc_screen_time	Aggregation	Today's PC screen time categorized by Productive, Entertainment, Communication, Browsing.
get_pc_performance	Telemetry	CPU load %, RAM total/free/used %, battery charge %, and AC state.
get_productivity_score	Analytics	Automated productivity score (0-100), balance ratio, and top distraction apps.
search_window_history	Search	Search application usage history today by process or window title query.
get_idle_status	Presence	User presence & idle duration (detects if user is actively typing or away).
get_recent_transitions	Chain	Chronological sequence of recent window and application switches.
get_system_health	Diagnostics	System resource health check, memory pressure level, and uptime.
get_top_distractions	Analytics	Identifies entertainment and distraction apps consuming the most time today.
get_hourly_breakdown	Historical	24-hour timeline of productive vs entertainment minutes per hour for any date.
get_historical_usage	Historical	Multi-day productivity scores, duration trends, and top apps across a date range.
get_unified_context	Cross-Device	Combined snapshot merging PC desktop activity with synced Android phone context.
get_cross_device_screen_time	Cross-Device	Total combined screen time across PC and mobile with device breakdown.
get_device_fleet	Cross-Device	Lists all connected devices (Windows PC + Android phones) with sync status.

---

🚀 Quick Start

1. Run via NPX (1-Click Execution)

npx windows-context-mcp --stdio

2. Build & Test Locally

npm install
npm test
npm run build
npm start

HTTP server starts on port 3001 with endpoint http://localhost:3001/mcp and live UI at http://localhost:3001.

---

🔗 AI Assistant Setup

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json)

{
  "mcpServers": {
    "windowsContext": {
      "command": "node",
      "args": ["C:/Users/smnk2/.gemini/antigravity/scratch/windows-context-mcp/dist/index.js", "--stdio"]
    }
  }
}

Google Gemini / ChatGPT (HTTP Mode)

{
  "mcpServers": {
    "windowsContext": {
      "url": "http://localhost:3001/mcp",
      "transport": "http"
    }
  }
}

---

📄 License

MIT License.