telos-mcp
Provides task management with full Obsidian compatibility, including markdown files, YAML frontmatter, wiki links, Dataview queries, and graph view integration.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@telos-mcp create a task to add rate limiting to the API"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpStable install
npm install -g telos-mcpOr from source:
git clone https://github.com/skye-flyhigh/telos-mcp.git
cd telos-mcp && npm install && npm run buildThen point your client to "command": "node", "args": ["/path/to/telos-mcp/dist/index.js"].
Configuration
Variable | Default | Description |
|
| Directory where task files are stored |
Set TELOS_DIR to override the default storage location:
TELOS_DIR=/custom/path npx telos-mcpOr 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 |
| Create a new task with subject, description, tags, dependencies, project_id |
| Update status, dependencies, project, or details of an existing task |
| Get full details of a task by ID |
| List all tasks (summary view), with optional filters |
| Delete a task by ID (removes the folder) |
| Move a task to a different project (or to global tasks) |
| Create multiple tasks at once |
| Get task hierarchy tree with all descendants |
Project Management
Tool | Description |
| Create a new project for organizing tasks |
| Get full project information by key |
| List all projects with optional filtering |
| Update project metadata |
| Archive a project (moves to archive/year/) |
Status Workflow
pending → planning → in_progress → reviewing → completed
↓ ↓ ↓ ↓
blocked archived deletedUse 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 completeWhen a task is completed, it's automatically removed from dependents'
blockedByWhen 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 projectsDataview 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 toolsproject_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
Scored across 13 tools
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.
All tool names follow a consistent verb_noun pattern: project_<verb> and task_<verb>, making it easy to predict functionality from the name.
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.
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
Related MCP Connectors
Project tracker for teams working with AI agents: issues, cycles, docs and shared agent memory.
Task management for teams building with AI agents. Agents claim tasks and report progress.
Personal project management with AI agents: numbered tickets, statuses, files, a thread per ticket.
Personal project management with AI agents: numbered tickets, statuses, files, a thread per ticket.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI-native task management using plain markdown files to create, update, query, and organize Epics, Stories, Tasks, and Milestones without requiring a database.-
- FlicenseNot gradedqualityDmaintenanceLightweight project management for teams and AI agents.-
- AlicenseBqualityDmaintenanceEnables AI agents and humans to collaboratively plan and manage tasks with a shared kanban and dependency graph, all stored locally.3129 npm82MIT
- AlicenseBqualityBmaintenanceA project tracker for teams of humans and AI agents that coordinates work through plain files (markdown and JSONL), providing an MCP server for agents and a CLI for humans.3972 npm1MIT