telos-mcp

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