SecondBrain MCP Server

A Model Context Protocol (MCP) server for managing WorkFlowy-based second brain structures, with specialized support for Brainlift documents and surgical content editing.

Installation

npm install -g secondbrain-mcp

Or run directly without installing:

npx secondbrain-mcp

Configuration

Prerequisites

You need a WorkFlowy account with your content organized in a hierarchical structure (see WorkFlowy Structure below).

Environment Variables

| Variable | Required | Description | |---|---|---| | WORKFLOWY_USERNAME | Yes | Your WorkFlowy email address | | WORKFLOWY_PASSWORD | Yes | Your WorkFlowy password | | WORKFLOWY_ROOT_NODE | Yes | The name of the root node in your WorkFlowy tree (e.g., "My Second Brain") |

Adding to Claude Desktop

Add this to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "secondbrain-mcp": {
      "command": "npx",
      "args": ["secondbrain-mcp"],
      "env": {
        "WORKFLOWY_USERNAME": "[email protected]",
        "WORKFLOWY_PASSWORD": "your-password",
        "WORKFLOWY_ROOT_NODE": "your-root-node-name"
      }
    }
  }
}

Adding to Claude Code

Add with the CLI:

claude mcp add secondbrain-mcp -- npx secondbrain-mcp

Then set the required environment variables in your shell or .env file.

Adding to Cursor / VS Code

Add to your .cursor/mcp.json or .vscode/mcp.json:

{
  "mcpServers": {
    "secondbrain-mcp": {
      "command": "npx",
      "args": ["secondbrain-mcp"],
      "env": {
        "WORKFLOWY_USERNAME": "[email protected]",
        "WORKFLOWY_PASSWORD": "your-password",
        "WORKFLOWY_ROOT_NODE": "your-root-node-name"
      }
    }
  }
}

Development

# Install dependencies
npm install

# Build the project
npm run build

# Start stdio transport (default)
npm run start

# Start SSE transport wrapper
npm run start:sse

Features

🧠 WorkFlowy Integration

• Connect to WorkFlowy accounts for second brain management
• Navigate organizational structures (Departments → People → Content)
• Read and update content with surgical precision

🎯 Path-Based Targeting

• Update specific sub-nodes without affecting other content
• Navigate to any depth in hierarchical structures
• Safe, surgical editing prevents accidental data loss

📚 Brainlift Structure Support

• Built-in validation for Brainlift document structure
• DOK framework support (DOK1-Facts, DOK2-Summaries, DOK3-Insights, DOK4-SPOVs)
• Section-specific editing (Owner, Purpose, Experts, Knowledge Tree)

🛡️ Safety Features

• Content preservation with targeted updates
• Structure validation and helpful feedback
• Full-content replacement write tool removed for safety

Available Tools

Core Navigation

• list-departments - List all departments in the organization
• list-persons - List all people in a specific department

Content Reading

• get-markdown - Get full person content as markdown
• get-markdown-at-path - Read content from specific paths
• get-brainlift-section - Read specific Brainlift sections

Content Writing

• set-markdown-at-path - Update content at specific paths (with Brainlift validation)
• create-markdown-at-path - Create missing path nodes, then write content at target path
• set-brainlift-section - Specialized Brainlift section editing

Analysis Tools

• analyze-logs - Analyze and categorize security logs
• compare-baseline - Compare anomaly vs baseline log data
• example_tool - Example tool for testing

Note: tool loading is auto-discovered at runtime. Use npm run build and startup logs to confirm the active tool set in your environment.

Project Structure

secondbrain-mcp/
├── secondbrain-mcp-server.js     # SSE wrapper entrypoint
├── src/
│   ├── tools/                    # Maintained MCP tools in source
│   │   ├── GetMarkdownTool.ts           # Read full person content
│   │   ├── GetMarkdownAtPathTool.ts     # Read specific paths
│   │   ├── SetMarkdownAtPathTool.ts     # Update specific paths
│   │   ├── GetBrainliftSectionTool.ts   # Read Brainlift sections
│   │   ├── SetBrainliftSectionTool.ts   # Update Brainlift sections
│   │   ├── ListDepartmentsTool.ts       # List departments
│   │   ├── ListPersonsTool.ts           # List people in department
│   │   └── ExampleTool.ts               # Example/testing
│   ├── secondBrain.ts            # Core WorkFlowy integration
│   └── index.ts                  # Server entry point
├── dist/                         # Compiled JavaScript
├── BRAINLIFT_TOOLS_GUIDE.md      # Detailed Brainlift usage guide
├── USAGE_EXAMPLES.md             # Path-based tools examples
├── package.json
└── tsconfig.json

WorkFlowy Structure

The server expects this organizational structure in WorkFlowy:

Organization Root
├── Department 1 (e.g., "Engineering")
│   ├── Person 1 (e.g., "John Doe")
│   │   ├── BrainLifts
│   │   │   ├── Brainlift 1: Title
│   │   │   │   ├── Owner
│   │   │   │   ├── Purpose
│   │   │   │   ├── DOK4 - SPOV
│   │   │   │   ├── DOK3 - Insights
│   │   │   │   ├── Experts
│   │   │   │   └── DOK2 - Knowledge Tree
│   │   │   └── Brainlift 2: Title
│   │   └── Exploration
│   │       ├── Emerging Brainlifts
│   │       └── Sandbox
│   └── Person 2
└── Department 2

Usage Examples

Basic Operations

// List all departments
list-departments({message: ""})

// List people in a department  
list-persons({departmentName: "Engineering"})

// Read full person content
get-markdown({
  departmentName: "Engineering",
  personName: "John Doe"
})

Path-Based Targeting

// Read specific Brainlift section
get-markdown-at-path({
  departmentName: "Engineering", 
  personName: "John Doe",
  path: ["BrainLifts", "Brainlift 1: My Project", "DOK4 - SPOV"]
})

// Update specific section without affecting others
set-markdown-at-path({
  departmentName: "Engineering",
  personName: "John Doe", 
  path: ["BrainLifts", "Brainlift 1: My Project", "DOK4 - SPOV"],
  markdown: "* New spiky point of view\n* Another provocative insight"
})

// Create path if needed, then write content
create-markdown-at-path({
  departmentName: "Engineering",
  personName: "John Doe",
  path: ["Exploration", "Q2 Themes", "AI Operations"],
  markdown: "* Candidate topic 1\n* Candidate topic 2"
})

Path matching is tolerant for common variants (for example Brainlifts vs BrainLifts, and & vs &).

Brainlift-Specific Operations

// Read Brainlift section (easier syntax)
get-brainlift-section({
  departmentName: "Engineering",
  personName: "John Doe",
  brainliftName: "Brainlift 1: My Project", 
  section: "Experts"
})

// Update Brainlift section with validation
set-brainlift-section({
  departmentName: "Engineering",
  personName: "John Doe",
  brainliftName: "Brainlift 1: My Project",
  section: "Experts", 
  content: "* Expert 1:\n  * who: Jane Smith, AI Researcher\n  * focus: Machine Learning\n  * why follow: Leading expert in neural networks\n  * where: Twitter @janesmith, LinkedIn"
})

Key Features & Benefits

🎯 Surgical Editing

• Update specific Brainlift sections without affecting others
• Navigate to any depth in the content hierarchy
• Preserve existing content while making targeted changes

🧠 Brainlift Intelligence

• Built-in validation for DOK framework (DOK1→DOK2→DOK3→DOK4)
• Section-specific guidance (Owner, Purpose, SPOV, Insights, Experts, Knowledge Tree)
• Automatic structure checking and helpful feedback

🛡️ Safety First

• Full-content replacement write tool removed
• Path validation prevents accidental overwrites
• Clear error messages and structure guidance

📊 Content Quality

• Real-time validation for Brainlift structure compliance
• Suggestions for improving SPOV "spikiness"
• Ensures proper expert profiles and source documentation

Documentation

• Brainlift Tools Guide - Comprehensive guide for Brainlift editing
• Usage Examples - Path-based tools examples and workflows
• Tool Migration Options - Understanding tool deprecation strategy

Learn More

• MCP Framework Github
• MCP Framework Docs
• WorkFlowy API - Underlying WorkFlowy integration