MCP Integration

What is MCP?

Model Context Protocol (MCP) is Anthropic's standard protocol for connecting AI tools to external data sources and APIs. It provides a standardized way for Claude and other AI assistants to:

Execute Actions (Tools)

Create and manage tasks
Update task metadata
Add AI planning and documentation
Search and filter tasks
View project statistics

Access Information (Resources)

Read BackMark configuration
Access task lists and details
View project statistics
Read workflow documentation
Understand task structure

With MCP, Claude can work with your BackMark tasks as naturally as you do - creating, updating, and managing tasks through conversational commands.

Why Use MCP with BackMark?

🔗 Seamless Integration

Claude Code natively understands your BackMark backlog. No copy-pasting, no context switching. Just natural conversation.

🤖 Full AI Autonomy

Claude can create tasks, plan implementations, document work, and perform self-reviews all within BackMark.

📊 Real-time Sync

Changes are immediately reflected in your task files. Everything stays in sync between CLI and AI assistant.

💬 Natural Language

"Create a task for authentication" - that's all it takes. Claude handles the rest.

🔍 Intelligent Search

Claude can search your tasks, understand context, and suggest relevant connections.

📈 Project Insights

Ask about project status, milestones, or workload - Claude has full visibility.

Quick Setup

Step 1: Build BackMark

First, ensure BackMark is built with MCP server support:

$ cd /path/to/backmark

$ npm run build

✓ Built successfully

Step 2: Configure Claude Code

Add the BackMark MCP server to your Claude Code settings:

Location: ~/.config/claude-code/settings.json

{
  "mcpServers": {
    "backmark": {
      "command": "node",
      "args": ["/absolute/path/to/backmark/dist/mcp-server.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Note: Replace /absolute/path/to/backmark with your actual BackMark installation path.

Step 3: Global Installation (Optional)

For easier setup, install BackMark globally:

$ npm run install:global

Then use this simpler config:

{
  "mcpServers": {
    "backmark": {
      "command": "backmark-mcp-server"
    }
  }
}

Step 4: Initialize Your Project

Make sure your project has a BackMark backlog:

$ cd /your/project

$ backmark init "My Project"

✓ Initialized BackMark in /your/project/backlog

🎉 You're ready! Restart Claude Code and start collaborating.

Available MCP Tools

Claude can use these tools to interact with your BackMark backlog:

Task Management

backmark_task_create - Create new task
backmark_task_list - List tasks with filters
backmark_task_view - View task details
backmark_task_edit - Edit task properties
backmark_task_close - Mark task as done

AI Collaboration

backmark_task_ai_plan - Add AI implementation plan
backmark_task_ai_note - Add timestamped note
backmark_task_ai_doc - Add documentation
backmark_task_ai_review - Add self-review

Project Overview

backmark_search - Fuzzy search tasks
backmark_overview - Get project stats
backmark_board_show - View Kanban board

Context Resources

backmark://config - Project configuration
backmark://tasks/all - All tasks list
backmark://docs/workflow - AI workflow guide
backmark://stats/overview - Statistics

Usage Examples

Creating Tasks

Simply ask Claude to create tasks naturally:

You: Create a BackMark task for implementing JWT authentication

Claude: I'll create that task for you.

[Uses backmark_task_create]

Claude: ✓ Created task #42: Implement JWT authentication

Priority: high

Assignee: Claude

Labels: feature, auth

AI Workflow in Action

Claude can autonomously manage the entire task lifecycle:

You: Work on task #42 and document your progress

Claude: I'll start working on the JWT authentication task.

[1. Adds AI plan via backmark_task_ai_plan]

[2. Implements the feature]

[3. Adds progress notes via backmark_task_ai_note]

[4. Generates docs via backmark_task_ai_doc]

[5. Performs self-review via backmark_task_ai_review]

Claude: ✓ Task completed! I've documented:

- Implementation plan

- Development notes with timestamps

- API documentation

- Self-review checklist

Querying Tasks

You: Show me all high priority tasks assigned to you

Claude: Let me check...

[Uses backmark_task_list with filters]

Claude: Found 3 high priority tasks assigned to me:

#42 Implement JWT authentication (In Progress)

#15 Add fuzzy search (To Do)

#28 Refactor API endpoints (Review)

Project Insights

You: What's the current status of the project?

Claude: Let me get the project overview...

[Uses backmark_overview]

Claude: Here's your project status:

📊 Total: 48 tasks

✅ Done: 28 (58%)

🔄 In Progress: 5

📋 To Do: 12

👀 Review: 3

🎯 v1.0 milestone is 80% complete

🚀 On track for release!

Advanced Configuration

Project-Specific Setup

Configure MCP server for a specific project directory:

{
  "mcpServers": {
    "backmark-myproject": {
      "command": "node",
      "args": ["/path/to/backmark/dist/mcp-server.js"],
      "cwd": "/path/to/your/project",
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

This makes the MCP server work only in that specific directory.

Multiple Projects

Set up MCP for different projects:

{
  "mcpServers": {
    "backmark-work": {
      "command": "backmark-mcp-server",
      "cwd": "/home/user/work-project"
    },
    "backmark-personal": {
      "command": "backmark-mcp-server",
      "cwd": "/home/user/personal-project"
    }
  }
}

Troubleshooting

MCP Server Not Starting

Check:

Dist directory exists with mcp-server.js
Node.js version is 18.0.0+
File paths in config are absolute
JSON syntax is valid

Test manually:

node /path/to/backmark/dist/mcp-server.js

"Backlog not initialized" Error

Solution:

cd your-project
backmark init "My Project"

The MCP server requires a backlog in the working directory.

Tools Not Appearing

Steps:

Restart Claude Code
Check settings.json syntax
Review Claude Code logs
Verify BackMark is built