HomeMCP Server

New

Telos MCP Server

Connect your screen-tracking data to Claude Desktop, Cursor, or other MCP-compatible AI tools. Query your work patterns, productivity, and time usage in plain English -- all from your local database, no cloud required.

Works with: Claude DesktopCursor IDEChatGPT (not yet)

What is MCP?

The Model Context Protocol is an open standard that lets AI assistants access external data sources and tools. The Telos MCP Server exposes your local activity database so any MCP-compatible client can query your work history, sessions, and productivity data.

Your data never leaves your machine. The MCP server reads directly from your local Telos database -- no cloud, no third-party access.

How It Connects to Your Data

The Telos MCP server is a small Python script that runs on your local machine. When you configure it in Claude Desktop or Cursor, here's what happens:

You ask a question

In Claude Desktop or Cursor, you type: "What did I work on today?"

AI picks the right tool

Claude/Cursor sees the Telos tools are available and automatically calls get_activity_today() on your local machine.

Server reads your local database

The MCP server opens ~/.telos/tracker.db (your local SQLite database) and retrieves your captures, sessions, and stats. This never leaves your computer.

AI receives the text response

The tool returns a formatted text summary (like "Today: 142 min work, 23 min learning...") to Claude/Cursor, which uses it to answer your question.

Important: Your Telos database stays on your machine. Only the text output from the tools (like "You worked 2h on coding") is sent to the AI model. No raw database files, no screenshots, no sensitive data.

Quick Setup

Install the MCP package

terminal

pip install mcp

Configure your MCP client

Add this to your client's MCP configuration file. Replace the path with where you installed Telos.

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "telos": {
      "command": "python",
      "args": ["/path/to/telos/client/mcp_server.py"]
    }
  }
}

Cursor — .cursor/mcp.json (in your project root)

.cursor/mcp.json

{
  "mcpServers": {
    "telos": {
      "command": "python",
      "args": ["/path/to/telos/client/mcp_server.py"]
    }
  }
}

Start asking questions

Restart your MCP client (fully quit and reopen). The Telos tools will appear automatically. Just ask in natural language.

Available Tools

The Telos MCP server exposes 7 tools. Your AI assistant picks the right one automatically based on what you ask.

get_activity_today

Today's complete activity breakdown: time spent per category, top apps, total captures, and latest activity.

Try asking:

"What did I do today?"

get_sessions

Work sessions with AI summaries, focus scores, apps used, and duration. Filter by date.

Try asking:

"Show me my work sessions from yesterday"

get_daily_summary

AI-generated daily narrative with productivity score, key learnings, and focus blocks.

Try asking:

"Give me my daily summary for Monday"

query_activity

Natural language search across all activity data -- captures, sessions, and summaries.

Try asking:

"How much time did I spend coding this week?"

get_recent_captures

Granular screen captures with detected app, task, files, URLs, and AI context.

Try asking:

"What was I working on 30 minutes ago?"

get_productivity_trends

Multi-day productivity scores and time breakdowns to spot patterns.

Try asking:

"Show my productivity trend for the last week"

get_top_apps

Most-used applications and category breakdown over a configurable time range.

Try asking:

"Which apps did I use most this week?"

Example Conversations

Here are real examples of what you can ask once the MCP server is connected. These work in Claude Desktop and Cursor (other MCP-compatible clients coming soon).

Note: ChatGPT doesn't support MCP yet, so these examples won't work there. Use Claude Desktop (desktop app) or Cursor IDE instead.

Quick Status Check

YOU

How's my day going so far?

You've been at it for about 4 hours today. Here's the breakdown:

Work: 142 min · Learning: 23 min · Browsing: 31 min
Top apps: VS Code (45 captures), Chrome (28), Terminal (12)
68 total captures across 8 sessions

Most of your morning was in VS Code working on the API refactor. You had a solid 45-minute deep focus block around 10am.

Deep Activity Query

YOU

What did I work on between 2pm and 5pm yesterday? I need to fill out my timesheet.

Here's your afternoon breakdown from yesterday:

14:00-14:45 · VS Code · Fixing pagination bug in user dashboard
14:50-15:20 · Slack + Zoom · Sprint planning meeting
15:25-16:30 · VS Code + Terminal · Writing integration tests for auth module
16:35-17:00 · Chrome + Notion · Updating project documentation

For your timesheet: ~1.5h coding (bug fix + tests), 30min meeting, 25min documentation.

Productivity Analysis

YOU

Am I spending too much time context-switching? Show me my app usage patterns this week.

Looking at your last 7 days, you used 14 different apps with 724 total captures:

VS Code: 38% · Chrome: 22% · Slack: 12% · Terminal: 8%
Categories: 65% work, 25% browsing, 8% learning, 2% entertainment

You're actually doing well -- 65% focused work time is above average. But I notice Slack captures spike between 11am-12pm every day. Consider batching your messages to protect your morning focus blocks.

Integration with Coding Workflow

YOU

I'm writing a standup update. What did I accomplish since yesterday morning?

Based on your tracked activity since yesterday 9am:

Yesterday: Fixed pagination bug, wrote auth integration tests, updated docs
Today: Started API refactor (mcp_server.py), reviewed PR #142, pair-programmed on deploy script

Here's a draft for your standup:

"Yesterday: Closed the pagination bug, added integration tests for auth, updated project docs. Today: Working on the API refactor and deploy pipeline. No blockers."

Advanced Configuration

Custom Database Path

If your Telos database is in a non-default location, set the TELOS_DB_PATH environment variable:

claude_desktop_config.json

{
  "mcpServers": {
    "telos": {
      "command": "python",
      "args": ["/path/to/telos/client/mcp_server.py"],
      "env": {
        "TELOS_DB_PATH": "/custom/path/to/tracker.db"
      }
    }
  }
}

HTTP Transport

For network-accessible setups, you can run the server with HTTP transport:

terminal

python mcp_server.py --transport http
# Server starts at http://localhost:8000/mcp

Testing with MCP Inspector

Use the official MCP Inspector to test and debug:

terminal

npx @modelcontextprotocol/inspector python client/mcp_server.py

Which AI Assistants Support MCP?

Claude Desktop

Anthropic's desktop app with full MCP support. Works on macOS and Windows.

Download: claude.ai/download

Cursor IDE

AI-powered code editor with MCP integration. Perfect for developer workflows.

Download: cursor.sh

ChatGPT

OpenAI's ChatGPT doesn't support MCP yet. You can use their API with custom code, but not the web/desktop app.

Other Clients

More MCP-compatible clients are launching. Check modelcontextprotocol.io for updates.

Privacy Note

The Telos MCP server runs entirely on your machine. It reads from your local SQLite database at ~/.telos/tracker.db. No data is sent to external servers. When you use it with Claude or Cursor, only the text output of the tools is shared with the AI model -- never raw screenshots or database files.