Obsidian Todos

You can run an MCP server that gives AI assistants direct access to your Obsidian todos through the Local REST API. This enables listing incomplete todos, adding new ones to today’s daily note, updating existing items, and viewing per-file statistics, all via simple MCP tools.

How to use

Use these tools from your MCP client to interact with your Obsidian vault. You can list all incomplete todos, add new todos to today’s daily note, update specific todos (including marking them complete), and fetch statistics about your todos by file. Each tool is designed to be invoked through your MCP integration to streamline your workflow with your Obsidian notes.

How to install

Prerequisites you must have before installing the MCP server.

1. Obsidian with these plugins enabled: Local REST API, Dataview, Todos REST API.

2. Node.js 18+.

From npm and from source

# From npm (coming soon)
npm install -g obsidian-todos-mcp-server

# From source
cd mcp-server
npm install
npm run build

Configuration

Configure how your MCP client connects to the Obsidian Local REST API. The server exposes a base URL and an optional API key for authentication.

# Environment variables
OBSIDIAN_API_URL=http://localhost:27124
OBSIDIAN_API_KEY=YOUR_API_KEY

Claude Desktop configuration

Configure Claude Desktop to find and start the Obsidian todos MCP server from your workspace.

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

Other startup options

If you install the binary directly after npm link, you can connect with the following configuration.

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

From source start example

If you start from source, run the server with Node using the built dist entry.

{
  "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

The MCP server provides four tools you can call from your client to manage Obsidian todos.

list_todos

Lists all incomplete todos from your Obsidian vault.

add_todo

Adds a new todo to today’s daily note.

update_todo

Updates an existing todo, such as marking it complete or changing its text.

get_todo_stats

Gets statistics about your todos, including per-file breakdowns.

Troubleshooting

Connection issues: Ensure Obsidian Local REST API is running, verify the API URL is correct (default: http://localhost:27124), and confirm the Todos REST API plugin is enabled in Obsidian.

Authentication: If authentication is enabled in Local REST API, set OBSIDIAN_API_KEY in your environment or update your client configuration with the API key.

Development

Development commands you may use while building and testing the MCP server.

# 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

License

MIT license.

Available tools

list_todos

Lists all incomplete todos from your Obsidian vault.

add_todo

Adds a new todo to today’s daily note.

update_todo

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

get_todo_stats

Gets statistics about your todos, including per-file breakdowns.