@contextberg/mcp-server

MCP (Model Context Protocol) server for Contextberg — Access your activity tracking data and Long-Term Memory from Claude Desktop, Claude Code, Codex, Cursor, and other MCP-compatible clients.

Migration note: This package was previously published as @screenest/mcp-server. The old name is deprecated — please update your config to @contextberg/mcp-server.

Prerequisites

• Contextberg installed and running (Windows WPF app or macOS app)
• Node.js 18 or higher

Quick Setup

No API token needed — just add the MCP server to your client config.

Use npx -y @contextberg/mcp-server directly on macOS and Linux. On Windows, run it through cmd /c so MCP clients can reliably launch npm commands.

macOS / Linux

Claude Code

Add to your settings JSON (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "contextberg": {
      "command": "npx",
      "args": ["-y", "@contextberg/mcp-server"]
    }
  }
}

Or via CLI:

npm i -g @contextberg/mcp-server
claude mcp add contextberg -- contextberg-mcp

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "contextberg": {
      "command": "npx",
      "args": ["-y", "@contextberg/mcp-server"]
    }
  }
}

Then completely quit and restart Claude Desktop.

Codex

Add via CLI:

codex mcp add contextberg -- npx -y @contextberg/mcp-server

Or edit ~/.codex/config.toml:

[mcp_servers.contextberg]
command = "npx"
args = ["-y", "@contextberg/mcp-server"]

Then restart Codex.

Cursor IDE

Edit .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "contextberg": {
      "command": "npx",
      "args": ["-y", "@contextberg/mcp-server"]
    }
  }
}

Then restart Cursor completely.

Windows

Claude Code

Add to your settings JSON (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "contextberg": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@contextberg/mcp-server"]
    }
  }
}

Or via CLI:

npm i -g @contextberg/mcp-server
claude mcp add contextberg -- contextberg-mcp

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "contextberg": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@contextberg/mcp-server"]
    }
  }
}

Then completely quit and restart Claude Desktop (closing the window is not enough — also exit from the system tray).

Codex

Add via CLI:

codex mcp add contextberg -- cmd /c npx -y @contextberg/mcp-server

Or edit %USERPROFILE%\.codex\config.toml:

[mcp_servers.contextberg]
command = "cmd"
args = ["/c", "npx", "-y", "@contextberg/mcp-server"]

Then restart Codex.

Cursor IDE

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

{
  "mcpServers": {
    "contextberg": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@contextberg/mcp-server"]
    }
  }
}

Then restart Cursor completely.

Alternative: Global Installation

For faster startup (no download on each launch):

npm install -g @contextberg/mcp-server

Then use the binary name directly:

{
  "mcpServers": {
    "contextberg": {
      "command": "contextberg-mcp"
    }
  }
}

Skill Guide (Recommended)

The MCP server exposes the tools; the skill guide teaches the agent when to use each tool. Install the Contextberg skill into your agent's project files:

# Codex
npx skills add contextberg/contextberg-skills --agent codex --skill contextberg -y

# Cursor
npx skills add contextberg/contextberg-skills --agent cursor --skill contextberg -y

The source repository includes .codex/skills/contextberg/SKILL.md, .cursor/skills/contextberg/SKILL.md, and other agent-specific formats.

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 | Full activity handoff packet: LTM, STM/reports, activity/input, browser, and agent history | | 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_agent_history | Coding agent (Claude Code / Codex / Cursor) conversation history |

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 a Contextberg activity handoff packet for the current work context. By default it combines the existing Local API sections into one markdown response: LTM, STM/reports, app activity timeline with typed input, browser context, and agent history.

For backward compatibility, passing date or app_filter returns the legacy filtered daily activity view.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | days | number | 1 | Trailing number of days to include, ending now. Max: 365 | | format | string | markdown | markdown or json | | activities | boolean | true | Include app activity timeline and attached input | | reports | boolean | true | Include STM/daily/hourly reports when available | | memory | boolean | true | Include Long-Term Memory | | agent_history | boolean | true | Include local coding agent history | | date | string | — | Legacy filtered view: target date in YYYY-MM-DD format | | app_filter | string | — | Legacy filtered view: filter to a specific application name |

Returns: Markdown text by default. The response includes # Contextberg Activity Handoff, ## Activity Timeline, ## Browser Context, and ## Agent History when those sources are enabled and available.

When format is json, large string fields may be truncated to stay within the MCP response budget, but the response remains valid JSON and includes truncated: true plus truncation metadata.

read_ltm

Reads the user's Long-Term Memory (LTM) — persistent context that the Contextberg 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.

get_agent_history

Returns coding agent (Claude Code / Codex / Cursor) conversation history from the user's local machine. Use to understand what the user has been working on with AI coding assistants.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | date | string | today | Target date in YYYY-MM-DD format (local timezone) | | source | string | all | Filter by agent: ClaudeCode, Codex, Cursor, or OpenClaw | | project | string | — | Filter by project name (partial match) | | max_sessions | number | 7 | Max sessions to return (max: 50) | | max_turns | number | 5 | Max turns per session (max: 100) | | max_chars | number | 200 | Max characters per Q/A field (max: 2000) |

Returns: Markdown text with session summaries and Q&A turns.

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, Codex, 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

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

Privacy & Data Handling

This MCP server exposes sensitive local data from the Contextberg 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): the full handoff packet, including LTM, STM/reports, activity/input, browser context, and coding agent history
• AI memory (get_daily_memory, get_weekly_memory): daily / weekly reports generated by Contextberg, 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

Contextberg app (local SQLite DB)
        ↓
  localhost:18080 (loopback only — no external access)
        ↓
@contextberg/mcp-server   ← this package
        ↓
  stdio (Claude Desktop / Codex / 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.

Security model

The Contextberg local API only accepts connections from the loopback interface. Remote connections are rejected with 403 Forbidden. No API token is required — the loopback restriction ensures only processes on your own machine can access the data.

What this server does NOT do

• No telemetry: the server makes no network calls except to localhost:18080 (the Contextberg 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 Contextberg'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

All variables are optional and rarely need changing. Pass them via the env block of your MCP client config:

{
  "mcpServers": {
    "contextberg": {
      "command": "npx",
      "args": ["-y", "@contextberg/mcp-server"],
      "env": {
        "CONTEXTBERG_LOG_LEVEL": "debug",
        "CONTEXTBERG_TIMEOUT_MS": "120000"
      }
    }
  }
}

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | CONTEXTBERG_API_URL | No | http://localhost:18080 | Contextberg local API endpoint. When unset, the server also falls back to http://127.0.0.1:18080 if localhost cannot connect. Change this only if Contextberg is running on a non-default port. | | CONTEXTBERG_LOG_LEVEL | No | info | Logger verbosity. One of debug, info, warn, error. Logs go to stderr only (stdout is reserved for the MCP protocol). | | CONTEXTBERG_TIMEOUT_MS | No | 60000 | HTTP request timeout in milliseconds. Increase for very large weekly reports over slow disks. |

Legacy env vars: SCREENEST_API_URL / SCREENEST_LOG_LEVEL / SCREENEST_TIMEOUT_MS are still honored as a fallback during the transition. Please migrate to the CONTEXTBERG_* variants.

Platform support

This package is cross-platform and supports macOS, Windows, and Linux MCP clients. The Contextberg desktop app must be running locally and exposing its loopback Local API.

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally (for testing)
npm start

Troubleshooting

"Contextberg is not running"

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

MCP server not showing in Claude / Codex / 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\
   • Codex: codex mcp list / codex mcp get contextberg
   • Cursor: Output panel → MCP

License

MIT