# Oscribble MCP Server
Model Context Protocol (MCP) server for [Oscribble](https://github.com/oscargavin/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`):
```json
{
"mcpServers": {
"oscribble": {
"command": "npx",
"args": ["-y", "@oscargavin/oscribble-mcp"]
}
}
}
```
Restart Claude Code and the MCP server will be available.
### Manual Installation
```bash
npm install -g @oscargavin/oscribble-mcp
```
Then configure Claude Code to use the installed binary:
```json
{
"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
```bash
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:
```json
{
"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](LICENSE) for details.
## Contributing
Issues and pull requests welcome at [github.com/oscargavin/oscribble-mcp](https://github.com/oscargavin/oscribble-mcp).
## Related
- [Oscribble Desktop App](https://github.com/oscargavin/oscribble) - The main task manager application
- [Model Context Protocol](https://modelcontextprotocol.io/) - Learn more about MCP
- [Claude Code](https://docs.claude.com/claude-code) - AI-powered coding assistant
