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

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