Which integrations are available for this server?

Provides tools to manage todos within an Obsidian vault, enabling AI assistants to list incomplete tasks, add new todos to daily notes, update existing entries, and retrieve productivity statistics via the Local REST API.

How do I use Obsidian Todos MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Obsidian Todos MCP Server add 'Submit the quarterly expense report' to my daily note" 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.

Obsidian Todos MCP Server

by mtuckerb

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

Obsidian Todos MCP Server

Model Context Protocol (MCP) server that provides AI assistants with direct access to Obsidian todos through the Local REST API.

Features

🔍 List todos - Get all incomplete todos from your vault
➕ Add todos - Create new todos in today's daily note
✏️ Update todos - Modify existing todos or mark them complete
📊 Get stats - View todo statistics by file

Related MCP server: Obsidian MCP Server

Prerequisites

Obsidian with the following plugins installed and enabled:
- Local REST API
- Dataview
- Todos REST API (this plugin)
Node.js 18+ installed

Installation

From npm (coming soon)

npm install -g obsidian-todos-mcp-server

From source

cd mcp-server
npm install
npm run build

Configuration

Environment Variables

OBSIDIAN_API_URL - Base URL for the REST API (default: http://localhost:27124)
OBSIDIAN_API_KEY - API key if authentication is enabled

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian-todos": {
      "command": "npx",
      "args": ["-y", "obsidian-todos-mcp-server"],
      "env": {
        "OBSIDIAN_API_URL": "http://localhost:27124"
      }
    }
  }
}

Or use the direct binary name after npm link:

{
  "mcpServers": {
    "obsidian-todos": {
      "command": "obsidian-todos-mcp",
      "env": {
        "OBSIDIAN_API_URL": "http://localhost:27124"
      }
    }
  }
}

Or if running from source:

{
  "mcpServers": {
    "obsidian-todos": {
      "command": "node",
      "args": ["/path/to/obsidian-todos-api/mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_API_URL": "http://localhost:27124"
      }
    }
  }
}

Available Tools

`list_todos`

Lists all incomplete todos from your Obsidian vault.

Example:

// No parameters needed
await use_mcp_tool({
  server_name: "obsidian-todos",
  tool_name: "list_todos",
  arguments: {}
});

`add_todo`

Adds a new todo to today's daily note.

Parameters:

text (string, required) - The todo text

Example:

await use_mcp_tool({
  server_name: "obsidian-todos",
  tool_name: "add_todo",
  arguments: {
    text: "Review pull requests"
  }
});

`update_todo`

Updates an existing todo (mark complete, change text, etc.).

Parameters:

file (string, required) - Path to file containing the todo
line (number, required) - Line number of the todo (0-indexed)
text (string, optional) - New text for the todo
completed (boolean, optional) - Mark as complete/incomplete

Example:

await use_mcp_tool({
  server_name: "obsidian-todos",
  tool_name: "update_todo",
  arguments: {
    file: "Daily/2025-10-31.md",
    line: 5,
    completed: true
  }
});

`get_todo_stats`

Get statistics about your todos.

Example:

await use_mcp_tool({
  server_name: "obsidian-todos",
  tool_name: "get_todo_stats",
  arguments: {}
});

Development

# Watch mode for development
npm run dev

# Build for production
npm run build

# Test the server
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js

Troubleshooting

Connection Issues

Ensure Obsidian Local REST API is running
Check the API URL is correct (default: http://localhost:27124)
Verify the Todos REST API plugin is enabled in Obsidian

Authentication Errors

If you have authentication enabled in Local REST API:

Set the OBSIDIAN_API_KEY environment variable
Or update your Claude Desktop config with the API key

License

MIT

Available Tools

5 tools

add_todoA

Add a new todo to today's daily note in Obsidian

ParametersJSON Schema

Name	Required	Description	Default
`text`	Yes	The todo text to add

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the behavioral burden. It mentions the specific location 'today's daily note', but does not disclose side effects like whether it creates the note if missing or appends to existing content.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no wasted words, effectively front-loading the key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool with one parameter and no output schema, the description is largely complete. It covers the what and where, though it omits details like error handling or insertion behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter 'text', so the baseline is 3. The tool description adds context about the destination but does not elaborate on parameter format or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Add', the object 'todo', and the specific location 'to today's daily note in Obsidian', distinguishing it from sibling tools like list_todos and update_todo.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for adding todos to today's note, but does not explicitly state when NOT to use it or mention alternatives among the sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_todo_statsC

Get statistics about todos (total, by file, etc.)

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

C2.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behaviors; it only states 'Get statistics' implicitly a read operation. No mention of side effects, authentication, or data scope, providing minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is concise but lacks structure. It conveys the basic purpose efficiently, yet a bit more detail (e.g., list of possible statistics) would improve without significant verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and sparse description, the tool's output is vague ('total, by file, etc.'). Agent may not know if it returns counts, breakdowns, or aggregate data, leading to uncertainty.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100% trivially. Baseline for zero parameters is 4; description adds no extra info but does not need to.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses specific verb 'Get statistics' and resource 'todos', with examples like 'total, by file, etc.' to indicate scope. It distinguishes from siblings like add_todo and list_todos, but could be more explicit about the types of statistics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance provided on when to use this tool versus alternatives. No mention of preferred use cases or exclusions, leaving the agent without decision support.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_due_datesB

List all due dates from tables under # Due Dates headings in Obsidian

ParametersJSON Schema

Name	Required	Description
`start`	No	Start date in YYYY-MM-DD format (optional)
`end`	No	End date in YYYY-MM-DD format (optional)
`query`	No	Query/tag filter (optional)

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It does not disclose whether the operation is read-only, requires authentication, or has any side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, focused sentence of 12 words. The key action and resource are front-loaded. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With three optional parameters and no output schema or annotations, the description is minimal. It does not specify output format or behavior for edge cases, but is sufficient for a simple list operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all three parameters. The description adds no further context about parameter usage beyond 'List all due dates', so baseline score applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'List' and the resource 'due dates from tables under # Due Dates headings in Obsidian'. This differentiates it from sibling tools like list_todos, which handles general todos.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives such as list_todos. There is no mention of prerequisites, limitations, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_todosC

List all incomplete todos from Obsidian vault using Dataview

ParametersJSON Schema

Name	Required	Description
`status`	No	The todo status (e.g. ' ', '!', '*'
`completed`	No	Do you want completed tasks only?
`path`	No	Only search beneath this path
`tag`	No	only match on these tags
`exclude`	No	A comma separated list of paths to exclude

TDQS

C2.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description mentions 'using Dataview' but does not disclose read-only nature, pagination, or side effects. For a listing tool, behavioral traits are under-specified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no fluff, but it is misleading (incomplete vs completed) and lacks necessary structure to earn its place fully.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 5 parameters, no output schema, and no annotations, the description is too sparse. It fails to explain filter interaction (AND/OR), default behavior, or output format, leaving significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. Description adds no extra meaning beyond what the schema already provides for parameters like status, completed, path, tag, exclude.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states 'list all incomplete todos', which is a specific verb and resource. However, it contradicts the schema's 'completed' parameter that allows listing completed tasks, reducing clarity. It distinguishes from sibling tools like add_todo and get_todo_stats, but not from list_due_dates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus siblings like list_due_dates or get_todo_stats. The description lacks any context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_todoC

Update an existing todo in Obsidian (mark complete, change text, etc.)

ParametersJSON Schema

Name	Required	Description
`file`	Yes	Path to the file containing the todo
`line`	Yes	Line number of the todo (0-indexed)
`text`	No	New text for the todo
`completed`	No	Whether the todo should be marked complete

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must convey behavioral traits. It only states 'update an existing todo' but fails to disclose idempotency, error handling (e.g., file not found), or whether updates overwrite or merge data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, efficient, and front-loaded with the essential information. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with four parameters and no output schema, the description lacks information on return values, success/failure indicators, or side effects. It leaves gaps for agent decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with clear descriptions for all four parameters, so the description adds no further semantic value beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('update an existing todo') and provides examples ('mark complete, change text'), but it does not explicitly differentiate from sibling tools like 'add_todo' or 'list_todos'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, such as when to modify an existing todo versus creating a new one with 'add_todo' or listing with 'list_todos'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

5 tool updatesv1.2.5May 31, 2026
- First observedadd_todo
- First observedget_todo_stats
- First observedlist_due_dates
- First observedlist_todos
- First observedupdate_todo

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored 2026-05-31 06:40 across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: add, update, list incomplete todos, list due dates, and get statistics. No overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern in snake_case (e.g., add_todo, list_todos, update_todo), making them predictable and easy to understand.

Tool Count5/5

With 5 tools, the server is well-scoped for a todo management domain. Each tool covers a core operation without excess or deficiency.

Completeness4/5

Covers create (add), read (list, stats, due dates), and update, but lacks a delete tool. This is a minor gap that agents can work around, but it's not fully complete.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

CalmLoop Task Manager
in.calmloop
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
Project Management Note Taking
1
Hint-Services-obsidian-github-mcp
ai.smithery
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Note Taking Version Control File Systems
29
mcpOAuth
net.todoist
Official Todoist MCP server for AI assistants to manage tasks, projects, and workflows.
App Automation Workplace & Productivity Project Management
2
OrbitOAuth
io.github.Noveum
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Project Management Workplace & Productivity
130

Related MCP Servers

Obsidian MCP Server
Note Taking Knowledge & Memory
fumi-sagawa
A
license
Not graded
quality
D
maintenance
Enables AI assistants to manage Obsidian notes via local REST API, supporting file CRUD, search, commands, and periodic notes.
Updated a year ago (2025-05-27 08:26 UTC)
6,222 npm
7
Apache 2.0
Obsidian MCP Server
Note Taking Search
louis030195
A
license
Not graded
quality
C
maintenance
Enables AI assistants to search, read, and analyze Obsidian notes via the Local REST API.
Updated a year ago (2025-10-20 23:30 UTC)
19 npm
18
ISC
ObsidianReaderMCP
Note Taking Knowledge & Memory
QianJue-CN
A
license
Not graded
quality
D
maintenance
Enables AI assistants to manage Obsidian vaults via the local REST API, supporting CRUD operations, batch processing, templates, and vault analytics.
Updated a year ago (2025-08-27 21:00 UTC)
MIT
Obsidian Tasks MCP Server
Note Taking Project Management
dss99911
A
license
Not graded
quality
D
maintenance
Enables AI assistants to manage Obsidian tasks with full CRUD operations, querying, and date-based filtering via MCP.
Updated 4 months ago (2026-05-16 06:01 UTC)
5
MIT