Skip to main content
Glama
Oscribble MCP Server
by oscargavin

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

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-mcp

Then 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 project

  • filter_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 project

  • task_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 project

  • task_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 project

  • task_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 project

  • task_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 build

Project 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

  1. Check your ~/.claude/claude_desktop_config.json syntax is valid JSON

  2. Restart Claude Code completely (quit and reopen)

  3. 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.

Available Tools

11 tools
oscribble_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

    A3.6/5.0

    Scored across 11 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers