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 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 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
- Check your
~/.claude/claude_desktop_config.jsonsyntax is valid JSON - Restart 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