Oscribble MCP Server
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., "@Oscribble MCP Server show me all unchecked tasks in my work project"
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.
Oscribble MCP Server
Model Context Protocol (MCP) server for Oscribble - enables Claude Code to interact with your Oscribble task projects through natural language.
What is this?
This MCP server exposes your Oscribble tasks to Claude Code, allowing you to:
List and filter tasks across projects
Complete or uncomplete tasks
View detailed task metadata (priorities, blockers, notes)
Add new tasks to projects
Query task status and dependencies
All through natural language conversation in Claude Code.
Related MCP server: Todoist Meeting MCP
Installation
Quick Start (Recommended)
Add this to your Claude Code MCP configuration (~/.claude/claude_desktop_config.json):
{
"mcpServers": {
"oscribble": {
"command": "npx",
"args": ["-y", "@oscargavin/oscribble-mcp"]
}
}
}Restart Claude Code and the MCP server will be available.
Manual Installation
npm install -g @oscargavin/oscribble-mcpThen configure Claude Code to use the installed binary:
{
"mcpServers": {
"oscribble": {
"command": "oscribble-mcp"
}
}
}Available Tools
oscribble_list_projects
List all Oscribble projects with paths and last accessed timestamps.
Example: "Show me all my Oscribble projects"
oscribble_list_tasks
List tasks from a project with optional status filtering.
Parameters:
project_name(string, required) - Name of the projectfilter_status(string, optional) - Filter by"all","checked", or"unchecked"(default:"all")
Examples:
"List all tasks in my work project"
"Show unchecked tasks in oscribble"
"What tasks are incomplete in my-project?"
oscribble_complete_task
Mark a task as complete.
Parameters:
project_name(string, required) - Name of the projecttask_id(string, required) - UUID of the task
Example: "Complete task abc-123 in my work project"
oscribble_uncomplete_task
Mark a task as incomplete.
Parameters:
project_name(string, required) - Name of the projecttask_id(string, required) - UUID of the task
Example: "Uncomplete task abc-123 in my work project"
oscribble_get_task_details
Get detailed information about a specific task including metadata, notes, and blockers.
Parameters:
project_name(string, required) - Name of the projecttask_id(string, required) - UUID of the task
Example: "Show me details for task abc-123 in oscribble"
oscribble_add_raw_task
Add raw task text to a project. The task will be formatted by Oscribble on next sync.
Parameters:
project_name(string, required) - Name of the projecttask_text(string, required) - Raw task text to append
Example: "Add 'Implement dark mode' to my work project"
Usage Examples
Here are some natural language queries you can use with Claude Code once the MCP server is configured:
"What tasks are blocked in oscribble?"
"Show me all critical priority tasks"
"List unchecked tasks across all projects"
"Complete the task about implementing dark mode"
"Add a new task to fix the login bug in my-app"
"What's the status of task abc-123?"How It Works
The MCP server reads and writes to the same storage location as the Oscribble desktop app (~/.project-stickies/), using:
Atomic writes - Temp file + rename pattern prevents data corruption
Safe concurrent access - Read operations work while the Oscribble app is open
Identical data structures - Uses the same TypeScript types as the main app
Storage Structure
~/.project-stickies/
├── settings.json # App-wide settings
├── projects.json # Project registry
└── {project-name}/
├── notes.json # Structured tasks (read/write)
├── raw.txt # Raw input (write for new tasks)
└── .context-cache/ # (Future use)Development
Building from Source
git clone https://github.com/oscargavin/oscribble-mcp.git
cd oscribble-mcp
npm install
npm run buildProject Structure
src/
├── index.ts # Main MCP server implementation
├── types.ts # TypeScript type definitions
└── utils.ts # Utility functions (file I/O, task operations)Testing Locally
After building, you can test the server locally by updating your Claude Code config to point to the built file:
{
"mcpServers": {
"oscribble": {
"command": "node",
"args": ["/path/to/oscribble-mcp/build/index.js"]
}
}
}Troubleshooting
"No projects found"
Make sure you've created at least one project in the Oscribble desktop app first. The MCP server reads from ~/.project-stickies/projects.json.
"Project not found"
Project names are case-sensitive. Use oscribble_list_projects to see the exact project names available.
"Notes file doesn't exist"
This project hasn't been formatted yet. Open the project in the Oscribble desktop app and format some tasks first.
MCP server not showing in Claude Code
Check your
~/.claude/claude_desktop_config.jsonsyntax is valid JSONRestart Claude Code completely (quit and reopen)
Check Claude Code logs at
~/Library/Logs/Claude/mcp.log(macOS)
Requirements
Node.js 18+ (for npx installation)
Oscribble desktop app - This MCP server is a companion to the main app
License
MIT License - see LICENSE for details.
Contributing
Issues and pull requests welcome at github.com/oscargavin/oscribble-mcp.
Related
Oscribble Desktop App - The main task manager application
Model Context Protocol - Learn more about MCP
Claude Code - AI-powered coding assistant
Available Tools
11 toolsoscribble_add_raw_taskA
Add raw task text to a project (will be formatted by Oscribble on next sync)
Inputs: project_name (required), task_text (required).
oscribble_begin_taskC
Begin timing a task - records start timestamp
Inputs: project_name (required), task_id (required).
oscribble_complete_taskC
Mark a task as complete in an Oscribble project
Inputs: project_name (required), task_id (required).
oscribble_complete_task_with_timingC
Complete a task and calculate duration from start time
Inputs: project_name (required), task_id (required).
oscribble_get_task_detailsB
Get detailed information about a specific task including metadata, notes, and blockers
Inputs: project_name (required), task_id (required).
oscribble_get_unblocked_tasksC
Get all tasks that are not blocked and ready to work on
Inputs: project_name (required).
oscribble_list_projectsA
List all Oscribble projects with their names, paths, and last accessed timestamps
Inputs: no named parameters.
oscribble_list_tasksC
List tasks from an Oscribble project with optional status filtering
Inputs: project_name (required), filter_status.
oscribble_search_tasksC
Search tasks by keyword in text and notes
Inputs: project_name (required), query (required).
oscribble_uncomplete_taskB
Mark a task as incomplete in an Oscribble project. Optionally log a failed attempt note with details about what was tried.
Inputs: project_name (required), task_id (required), attempt_note.
oscribble_update_taskC
Update task properties (text, priority, effort estimate, deadline, or notes)
Inputs: project_name (required), task_id (required), text, priority, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool has a clearly distinct purpose targeting specific operations in the Oscribble task management domain. For example, oscribble_begin_task starts timing, oscribble_complete_task marks completion, and oscribble_complete_task_with_timing adds duration calculation, with no significant overlap or ambiguity between them.
All tool names follow a consistent verb_noun pattern with the 'oscribble_' prefix, such as oscribble_add_raw_task, oscribble_list_projects, and oscribble_update_task. This uniformity makes the tool set predictable and easy to navigate for an agent.
With 11 tools, the server provides a well-scoped set that covers essential task management operations without being overwhelming. This count is appropriate for handling projects, tasks, timing, and status updates in a focused domain.
The tool set offers comprehensive CRUD and lifecycle coverage for task management, including creating (add_raw_task), reading (list_tasks, get_task_details), updating (update_task), and deleting equivalents (complete/uncomplete), along with search, timing, and project listing, leaving no obvious gaps for core workflows.
Maintenance
Related MCP Connectors
Manage Redbooth tasks, task lists, comments, tags and files from Claude and other AI assistants.
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
Capture, clarify and plan your tasks from Claude or ChatGPT. Built around the GTD methodology.
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Related MCP Servers
- AlicenseBqualityDmaintenanceIntegrates Claude with Todoist for natural language task management, supporting project and section organization, task creation, updating, completion, and deletion using everyday language.1926 npm22MIT
- AlicenseAqualityDmaintenanceConnects Claude to Todoist for transforming meeting notes into actionable tasks with inferred due dates and priorities. It enables full task lifecycle management, including creating subtasks, listing projects, and completing tasks through natural language.7MIT
- AlicenseBqualityDmaintenanceEnables Claude to interact with task management data in the Things app, including creating tasks, managing projects, searching, and organizing priorities.211MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to manage Todoist tasks and projects, including creating, listing, updating, completing tasks, and managing projects with natural language.MIT