You enable Claude Code to talk to your Oscribble task projects through a dedicated MCP server. This bridge lets you list, filter, complete, and add tasks using natural language, making task management across projects quick and hands-free.

How to use

Connect your MCP client to the Oscribble MCP server to start issuing natural language requests. You can list projects, view and filter tasks, mark tasks as complete or incomplete, fetch detailed task metadata, and add new tasks to projects. Use conversational queries like “Show me all tasks in my work project,” “Complete task abc-123 in my work project,” or “Add 'Implement dark mode' to my work project.” The MCP server operates by reading and writing to the same local storage used by the Oscribble desktop app, ensuring your data stays synchronized and consistent.

How to install

Prerequisites you need before installing the MCP server:

Node.js 18+ must be available on your system.

Oscribble desktop app should be installed and configured on your machine to enable proper data access.

# Quick Start (recommended)

# Add this MCP configuration to your Claude Code setup
# in ~/.claude/claude_desktop_config.json
{
  "mcpServers": {
    "oscribble": {
      "command": "npx",
      "args": ["-y", "@oscargavin/oscribble-mcp"]
    }
  }
}

Restart Claude Code after saving the config to make the MCP server available.

If you prefer to install and run the MCP server locally, follow these steps to install globally and point Claude Code to the binary.

Manual Installation

npm install -g @oscargavin/oscribble-mcp

Then configure Claude Code to use the installed binary:

{ "mcpServers": { "oscribble": { "command": "oscribble-mcp" } } }

After configuring, restart Claude Code to activate the MCP server.

Additional notes and troubleshooting

If you encounter issues starting the MCP server, verify your Claude Code configuration is valid JSON and that Claude Code is fully restarted after changes. Common checks include ensuring the MCP server appears in the list of available servers and that there are no syntax errors in your config.

If no projects are detected, ensure you have at least one project created in the Oscribble desktop app; the MCP server reads from the local projects registry.

For case-sensitive project names, use the exact project names reported by the MCP server, retrievable via the available list commands.

If Claude Code cannot display the MCP server, retry starting Claude Code after validating the config file, and check the logs for any startup errors.

Dependency and development notes

The MCP server is designed to be used with the Oscribble desktop app and relies on local storage for task data. It supports atomic writes and safe concurrent reads to maintain data integrity while the Oscribble app is in use.

~/.project-stickies/
├── settings.json
├── projects.json
└── {project-name}/
    ├── notes.json
    ├── raw.txt
    └── .context-cache/

This structure helps the MCP server format and access tasks in a familiar, version-safe way.

## Troubleshooting

No projects found: Create 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 the exact name shown by the OScribble project list.

Notes file doesn't exist: Open the project in Oscribble and format some tasks to generate the notes.json file.

MCP server not showing in Claude Code: Ensure your Claude Code config JSON is valid, restart Claude Code completely, and check the logs at ~/Library/Logs/Claude/mcp.log on macOS (path may vary by OS).

## Supported tools and endpoints

The MCP server exposes the following capabilities to Claude Code through natural language commands.

## Available tools

### oscribble\_list\_projects

List all Oscribble projects with paths and last accessed timestamps.

### oscribble\_list\_tasks

List tasks from a project with optional status filtering.

### oscribble\_complete\_task

Mark a task as complete.

### oscribble\_uncomplete\_task

Mark a task as incomplete.

### oscribble\_get\_task\_details

Get detailed information about a specific task including metadata, notes, and blockers.

### oscribble\_add\_raw\_task

Add raw task text to a project to be formatted on the next sync.