Skip to main content
Glama

telos-mcp

Task planning and tracking for AI agents. An MCP server with project-based organization and Obsidian-compatible markdown storage.

What it does

Gives any MCP-compatible AI agent persistent task management:

  • Create, update, list, delete tasks with full status tracking

  • Projects — organize tasks by project with metadata (tech stack, repo URL, sources)

  • Dependencies — blockedBy/blocks relationships between tasks

  • Bulk operations — create multiple tasks at once

  • Task tree — hierarchical view of tasks with parent-child relationships

  • Markdown files — each task is a folder with README.md and YAML frontmatter

  • Obsidian integration — full compatibility with Obsidian vaults, Dataview, and wiki links

  • Zero native addons — pure JavaScript, works on any Node version without rebuild

  • Multi-agent — owner tracking so you know who's doing what

Related MCP server: Plate MCP

Quick start

npx telos-mcp

Stable install

npm install -g telos-mcp

Or from source:

git clone https://github.com/skye-flyhigh/telos-mcp.git
cd telos-mcp && npm install && npm run build

Then point your client to "command": "node", "args": ["/path/to/telos-mcp/dist/index.js"].

Configuration

Variable

Default

Description

TELOS_DIR

~/.telos

Directory where task files are stored

Set TELOS_DIR to override the default storage location:

TELOS_DIR=/custom/path npx telos-mcp

Or in the MCP config:

{
  "mcpServers": {
    "telos": {
      "command": "npx",
      "args": ["telos-mcp"],
      "env": { "TELOS_DIR": "/custom/path" }
    }
  }
}

Client Setup

Claude Code

Add to .claude.json:

{
  "mcpServers": {
    "telos": {
      "type": "stdio",
      "command": "npx",
      "args": ["telos-mcp"],
      "env": {}
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "telos": {
      "command": "npx",
      "args": ["telos-mcp"]
    }
  }
}

Tools

Task Management

Tool

Description

task_create

Create a new task with subject, description, tags, dependencies, project_id

task_update

Update status, dependencies, project, or details of an existing task

task_get

Get full details of a task by ID

task_list

List all tasks (summary view), with optional filters

task_delete

Delete a task by ID (removes the folder)

task_move

Move a task to a different project (or to global tasks)

task_create_bulk

Create multiple tasks at once

task_tree

Get task hierarchy tree with all descendants

Project Management

Tool

Description

telos_project_create

Create a new project for organizing tasks

telos_project_get

Get full project information by key

telos_project_list

List all projects with optional filtering

telos_project_update

Update project metadata

telos_project_archive

Archive a project (moves to archive/year/)

Status Workflow

pending → planning → in_progress → reviewing → completed
   ↓          ↓           ↓            ↓
blocked   archived    deleted

Use status: "deleted" in task_update to remove a task (same as task_delete). Use status: "archived" to preserve task history without active tracking.

Dependencies

Tasks can block each other:

  • blockedBy: [1, 3] — this task can't start until tasks 1 and 3 complete

  • When a task is completed, it's automatically removed from dependents' blockedBy

  • When a task is deleted, all dependency references are cleaned up

Storage Format

Directory Structure

~/.telos/
├── tasks/                          # Global tasks (no project)
│   └── {id}-{slug}/
│       └── README.md
├── projects/
│   └── {key}/                      # e.g., "mnemo", "black-cat"
│       ├── project.md            # Project metadata
│       └── tasks/
│           └── {id}-{slug}/
│               └── README.md
└── archive/
    └── {year}/
        └── {key}/                  # Archived projects preserved
            ├── project.md
            └── tasks/

Task Format

Each task is a folder with a README.md containing YAML frontmatter:

---
id: 1
project_id: mnemo
subject: Fix authentication bug
status: in_progress
created: 2026-03-06T10:00:00.000Z
updated: 2026-03-06T12:30:00.000Z
owner: claude
activeForm: Fixing authentication bug
blockedBy: [3]
blocks: [5, 7]
tags: [backend, auth]
depth: 0
sources:
  - https://docs.example.com
  - https://github.com/org/repo/issues/42
---

Detailed description with full markdown support.

Project Format

Each project is a project.md file with YAML frontmatter and markdown body:

---
key: mnemo
display_name: Mnemo MCP
tech_stack: [typescript, mcp]
repo_url: "https://github.com/skye-flyhigh/mnemo"
status: active
created: "2026-03-06T10:00:00.000Z"
updated: "2026-03-06T12:00:00.000Z"
archived_at: null
archived_reason: null
sources:
  - https://modelcontextprotocol.io
---

Memory management for AI agents. Description goes here as markdown body.

Obsidian Integration

Telos is designed for Obsidian compatibility:

  • Markdown files — Every task is a README.md, every project is a project.md

  • YAML frontmatter — Metadata in standard YAML format

  • Wiki links — [[project-key]] links between tasks and projects

  • Dataview queries — Dynamic tables for task and project lists

  • Graph view — Visual task ↔ project relationships

Open ~/.telos as an Obsidian vault for full visualization.

License

MIT

Available Tools

13 tools
project_archiveA

Archive a project (moves to archive/year/)

Inputs: key (required), force, reason.

project_createC

Create a new project for organizing tasks

Inputs: key (required), display_name (required), clone, sources, +4 more.

project_getB

Get project information by key

Inputs: key (required).

project_listC

List all projects with optional filtering

Inputs: sort, limit, offset, search, +2 more.

project_updateD

Update project

Inputs: key (required), display_name (required), sources, repo_url, +3 more.

task_createC

Create a new task for tracking work

Inputs: subject (required), tags, owner, sources, +5 more.

task_create_bulkC

Create multiple tasks at once

Inputs: tasks (required), project_id.

task_deleteA

Delete a task by ID (removes the folder)

Inputs: taskId (required).

task_getA

Get full details of a task by ID

Inputs: taskId (required).

task_listA

List all tasks (summary view: id, subject, status, owner, blockedBy)

Inputs: owner, status, project_id.

task_moveC

Move a task to a different project (or to global tasks)

Inputs: taskId (required), project_id.

task_treeB

Get task hierarchy tree with all descendants

Inputs: rootId.

task_updateB

Update an existing task's status, dependencies, or details

Inputs: taskId (required), tags, owner, status, +8 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a distinct action on either projects or tasks, with no overlapping purposes. For example, project_create and task_create are clearly differentiated by resource type.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern: project_<verb> and task_<verb>, making it easy to predict functionality from the name.

    Tool Count4/5

    With 13 tools, the count is appropriate for a project and task management domain. It covers core operations without being overwhelming, though slightly on the higher side.

    Completeness4/5

    The set covers CRUD for tasks fully (create, get, list, update, delete) and for projects (create, get, list, update, archive). Missing an explicit project delete, but archive serves as a soft delete. A project tree might be useful but is not essential.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers