oscargavin/oscribble-mcp

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.

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