npm package: @screenest/mcp-server
Description: MCP server for ScreeNest — query your activity tracking data, AI-generated daily/weekly reports, and Long-Term Memory from Claude Desktop, Cursor, and other MCP-compatible clients.
Author: ScreeNest Team
Latest version: 1.0.1

# @screenest/mcp-server

MCP (Model Context Protocol) server for [ScreeNest](https://screenest.app) — Access your activity tracking data and Long-Term Memory from Claude Desktop, Cursor, and other MCP-compatible clients.

## Prerequisites

- **ScreeNest** installed and running (Windows only — ScreeNest is a WPF desktop app)
- **Node.js 18** or higher

## Setup

### Step 1 — Get your API token from ScreeNest

1. Open the **ScreeNest** desktop app
2. Go to the **Export** tab
3. Locate the **API Token** field (it's masked by default — click the eye icon to reveal)
4. Click the **Copy** button to copy the token to your clipboard

> **Why is a token needed?** The MCP server connects to ScreeNest's local HTTP API on `localhost:18080`. The token authenticates every request so that only your MCP client — not other processes on your machine — can read your activity data and Long-Term Memory. If you regenerate the token in ScreeNest, update your MCP client config with the new value and restart the client.

### Step 2 — Add the MCP server to your client config

#### Claude Desktop

Edit `claude_desktop_config.json`:

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` *(Note: ScreeNest itself is Windows-only)*

```json
{
  "mcpServers": {
    "screenest": {
      "command": "npx",
      "args": ["-y", "@screenest/mcp-server"],
      "env": {
        "SCREENEST_API_TOKEN": "<paste-your-token-here>"
      }
    }
  }
}
```

Replace `<paste-your-token-here>` with the token you copied in Step 1. Then **completely quit and restart Claude Desktop** (closing the window is not enough — also exit from the system tray).

#### Cursor IDE

Edit `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global):

```json
{
  "mcpServers": {
    "screenest": {
      "command": "npx",
      "args": ["-y", "@screenest/mcp-server"],
      "env": {
        "SCREENEST_API_TOKEN": "<paste-your-token-here>"
      }
    }
  }
}
```

Then restart Cursor completely.

## Alternative: Global Installation

For faster startup (no download on each launch):

```bash
npm install -g @screenest/mcp-server
```

Then configure with the binary name instead of `npx`:

```json
{
  "mcpServers": {
    "screenest": {
      "command": "screenest-mcp",
      "env": {
        "SCREENEST_API_TOKEN": "<paste-your-token-here>"
      }
    }
  }
}
```

## Windows Troubleshooting

If `npx` doesn't work on Windows, use the full path to node:

```json
{
  "mcpServers": {
    "screenest": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\Users\\<username>\\AppData\\Roaming\\npm\\node_modules\\@screenest\\mcp-server\\build\\index.js"
      ],
      "env": {
        "SCREENEST_API_TOKEN": "<paste-your-token-here>"
      }
    }
  }
}
```

Replace `<username>` with your actual Windows username.

## Available Tools

| Tool | Purpose |
|------|---------|
| `get_daily_memory` | AI-generated daily/hourly reports for a given date |
| `get_weekly_memory` | Weekly summary: daily reports, app breakdown, trends |
| `get_activity` | Raw activity data: app timeline, keystrokes, clipboard, browser visits |
| `read_ltm` | Read the user's Long-Term Memory (optionally a single section) |
| `update_ltm` | Append or replace a section of the Long-Term Memory |

### `get_daily_memory`

Returns AI-analyzed hourly and daily reports for a specific date. Use this for questions like "What did I do today?" or "Summarize yesterday's work".

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `date` | string | today | Target date in `YYYY-MM-DD` format (local timezone) |

**Returns:** Markdown text listing each AI report with title, type, timestamp, and formatted content.

---

### `get_weekly_memory`

Returns a weekly summary — daily AI reports, daily breakdown, top apps, and trends. Does NOT include raw per-entry logs (optimized for efficient context usage over longer ranges).

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `end_date` | string | today | End date in `YYYY-MM-DD` format (local timezone) |
| `days` | number | 7 | Number of days to look back (1–30) |
| `include` | array | all | Sections: `daily_reports`, `daily_breakdown`, `top_apps`, `trends` |

**Returns:** Text summary.

---

### `get_activity`

Returns the raw activity timeline for a given date — app usage, keystrokes per region (editor / terminal / AI sidebar), clipboard history, and browser visits. Use this when you need granular per-app data.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `date` | string | today | Target date in `YYYY-MM-DD` format (local timezone) |
| `app_filter` | string | — | Filter to a specific application name |

**Returns:** Markdown text with an activity timeline, clipboard, and browser sections.

---

### `read_ltm`

Reads the user's Long-Term Memory (LTM) — persistent context that the ScreeNest app maintains about the user's work style, tools, expertise, and current context.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `section` | string | — | Section name to read. Omit for full content. |

Common sections: `Work Style`, `Toolbox & Stack`, `Expertise`, `Communication`, `Interests`, `Current Context`.

**Returns:** The requested LTM content as Markdown.

---

### `update_ltm`

Updates the user's Long-Term Memory. Appends to a section by default, or replaces it entirely when `replace: true`. Importance tags like `[Priority: High] [Weight: 5]` can be included in the content.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `section` | string | required | Section name to update |
| `content` | string | required | Markdown content to write |
| `replace` | boolean | `false` | `true` to replace the section, `false` to append |

**Returns:** Confirmation message with action type and total character count.

---

## Response Size Limit

To avoid context overflow in the calling AI, responses are truncated at ~80,000 characters. If a response is truncated, narrow the query with `app_filter` or a more specific date.

## Example Usage

After setup, ask Claude or Cursor:

- "What did I work on today?"
- "Summarize my last week"
- "Which apps did I use most yesterday?"
- "What was I typing in VS Code this morning?"
- "Read my Long-Term Memory current context"
- "Update my LTM: I started working on the MCP server today"

## Timezone Note

ScreeNest stores all timestamps in **UTC** internally. Date parameters (`date`, `end_date`) should be specified in your **local timezone** (e.g., `2026-02-22`). The ScreeNest app handles UTC conversion automatically on the server side.

## Privacy & Data Handling

This MCP server exposes sensitive local data from the ScreeNest desktop app to your connected AI client. Before using it, please understand what is shared and with whom.

### What data can be accessed

Depending on which tool is invoked, the server can read:

- **Activity data** (`get_activity`): app usage timeline, keystrokes grouped by application, clipboard history, browser visit URLs
- **AI memory** (`get_daily_memory`, `get_weekly_memory`): daily / weekly reports generated by ScreeNest, including titles and summaries of your work
- **Long-Term Memory** (`read_ltm`, `update_ltm`): your work style, tools, expertise, current context — and the ability to modify it

### How the data flows

```
ScreeNest app (local SQLite DB)
        ↓
  localhost:18080 (Bearer token auth)
        ↓
@screenest/mcp-server   ← this package
        ↓
  stdio (Claude Desktop / Cursor / other MCP client)
        ↓
  the client's backing LLM provider (Anthropic, OpenAI, etc.)
```

When you invoke a tool from your MCP client, the requested data is handed to the client over stdio, and the client may forward it to its configured LLM provider as conversation context. That forwarding is governed by the privacy policy of the MCP client and its LLM provider — **not** by this package.

### What this server does NOT do

- **No telemetry**: the server makes no network calls except to `localhost:18080` (the ScreeNest app) and to its stdio parent (the MCP client). No analytics, no phone-home, no crash reporting.
- **No third-party services**: no external APIs are contacted directly from this package.
- **No persistent logging of your data**: nothing is written to disk by this package. Log messages (if enabled) are emitted to stderr only for the lifetime of the process.

You can verify these claims by reading `build/index.js` after `npm install` — the compiled source is not minified.

### Recommendations

- Treat `update_ltm` carefully: anything you pass to this tool is persisted in ScreeNest's Long-Term Memory and becomes part of future AI reports.
- Before sharing activity data via chat, remember that the LLM provider your client uses may log or retain the input per its own terms.
- If your MCP client supports per-tool approval prompts, consider enabling them so you can review what's being sent for each call.

## Environment Variables

`SCREENEST_API_TOKEN` is **required**. All other variables are optional and rarely need changing. Pass them via the `env` block of your MCP client config:

```json
{
  "mcpServers": {
    "screenest": {
      "command": "npx",
      "args": ["-y", "@screenest/mcp-server"],
      "env": {
        "SCREENEST_API_TOKEN": "<paste-your-token-here>",
        "SCREENEST_LOG_LEVEL": "debug",
        "SCREENEST_TIMEOUT_MS": "120000"
      }
    }
  }
}
```

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SCREENEST_API_TOKEN` | **Yes** | — | Bearer token for the ScreeNest local API. Copy it from the ScreeNest app's **Export** tab (see [Setup](#setup)). The server exits immediately if this is not set. |
| `SCREENEST_API_URL` | No | `http://localhost:18080` | ScreeNest local API endpoint. Change this only if ScreeNest is running on a non-default port. |
| `SCREENEST_LOG_LEVEL` | No | `info` | Logger verbosity. One of `debug`, `info`, `warn`, `error`. Logs go to stderr only (stdout is reserved for the MCP protocol). |
| `SCREENEST_TIMEOUT_MS` | No | `60000` | HTTP request timeout in milliseconds. Increase for very large weekly reports over slow disks. |

### Platform support

This package ships with `"os": ["win32"]` because the ScreeNest desktop application is Windows-only (WPF). `npm install` / `npx` will refuse to install on macOS or Linux.

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run locally (for testing)
npm start
```

## Troubleshooting

### "ScreeNest is not running"

The MCP server requires the **ScreeNest desktop application** to be running. Start ScreeNest first, then retry the MCP tool call.

### MCP server not showing in Claude / Cursor

1. Check JSON syntax in your config file
2. Restart the application completely (not just close window)
3. Check logs:
   - Claude Desktop (Mac): `~/Library/Logs/Claude/mcp*.log`
   - Claude Desktop (Windows): `%APPDATA%\Claude\logs\`
   - Cursor: Output panel → MCP

### Server exits with "SCREENEST_API_TOKEN is not set"

You haven't configured the token in your MCP client config. Follow [Step 1 of the Setup section](#step-1--get-your-api-token-from-screenest) to copy the token from the ScreeNest Export tab, then paste it into the `env.SCREENEST_API_TOKEN` field of your client config and restart the client.

### Authentication errors (401 / 403)

The token in your config is no longer valid. This usually means you clicked **Regenerate** or **Revoke** in the ScreeNest Export tab. To fix:

1. Open the ScreeNest app → Export tab
2. Copy the current API Token
3. Update `env.SCREENEST_API_TOKEN` in your MCP client config
4. Restart your MCP client completely

## License

MIT