Second Brain MCP Server

An MCP (Model Context Protocol) server that helps you create structured markdown notes from your Claude Code sessions. Capture commands executed, file changes, conversation summaries, and code snippets, then organize everything into a searchable second brain.

Features

Session Capture & Analysis

Pattern Detection: Automatically identifies session type (🆕 New Feature, 🐛 Bug Fix, ♻️ Refactoring, 📝 Documentation, ⚙️ Configuration, ✅ Testing)
Complexity Analysis: Simple file count-based classification (🟢 Simple: <3 files, 🟡 Moderate: 3-7 files, 🔴 Complex: 8+ files)
Automatic Organization: Notes organized by project into subdirectories
Rich Metadata: Captures commands, file changes, code snippets, and summaries with structured metadata
Clean Markdown: Readable format with emoji indicators and Key Changes bullets

Search & Discovery

Advanced Search: Multi-criteria filters (project, tags, pattern, complexity, date range, text query) with relevance scoring
Similarity Search: Find related sessions using Jaccard similarity across tags, patterns, and projects
Unified Search Tool: Single search_notes tool handles both text search and similarity search

Weekly Reports

Comprehensive Summaries: Statistics on sessions, files changed, and commands executed
Pattern & Complexity Distribution: Visual breakdown of work patterns and complexity levels
Project Breakdown: Sessions grouped by project
Session List: Chronological list of all sessions with summaries

Technical

No External Dependencies: Everything runs locally without API keys or external services
Metadata Caching: Fast queries with JSON metadata files
Flexible Configuration: Customize where notes are stored
TypeScript: Full type safety with comprehensive test coverage

Installation

Clone or download this repository
Install dependencies:

pnpm install

Build the TypeScript code:

pnpm run build

Configuration

Add the MCP server to your Claude Code configuration file (~/.claude/settings.local.json):

{
  "mcpServers": {
    "second-brain": {
      "command": "node",
      "args": ["/absolute/path/to/second_brain_mcp/build/index.js"]
    }
  }
}

Replace /absolute/path/to/second_brain_mcp with the actual path to this project.

Notes Directory Configuration

By default, notes are saved to ~/notes (your home directory). You can customize this in two ways:

Option 1: Environment Variable (Recommended)

Set the SECOND_BRAIN_NOTES_DIR environment variable:

export SECOND_BRAIN_NOTES_DIR=~/Documents/my-notes

Or add it to your MCP server configuration:

{
  "mcpServers": {
    "second-brain": {
      "command": "node",
      "args": ["/absolute/path/to/second_brain_mcp/build/index.js"],
      "env": {
        "SECOND_BRAIN_NOTES_DIR": "/home/username/Documents/my-notes"
      }
    }
  }
}

Option 2: Per-Tool Parameter

Pass notesDirectory parameter when calling any tool (overrides environment variable):

Please capture this session with notesDirectory: "/path/to/custom/notes"

Priority: Tool parameter > Environment variable > Default (~/notes)

Available Tools

This MCP server provides 3 focused tools for managing your session notes:

Tool	Purpose
`capture_session_note`	Capture and save detailed session notes with automatic pattern and complexity analysis
`search_notes`	Search notes with advanced filters, text search, and similarity-based discovery
`generate_weekly_report`	Generate comprehensive weekly summary reports

Usage

Once configured, you can use these tools in your Claude Code conversations:

Basic Example

Please capture this session with the summary:
"Implemented user authentication with JWT tokens"

Full Example with All Fields

Please capture this session note:

Summary: "Implemented user authentication system with JWT tokens and refresh token rotation"

Project: "my-web-app"

Topic: "authentication"

Commands executed:
- npm install jsonwebtoken bcrypt
- npm run test

File changes:
- Created: src/auth/jwt.ts - JWT token generation and validation
- Modified: src/server.ts - Added authentication middleware
- Created: src/auth/routes.ts - Login and registration endpoints

Code snippets:
- The JWT validation middleware (from src/auth/middleware.ts)
- The token generation function (from src/auth/jwt.ts)

Tags: authentication, security, jwt, backend

Working directory: /home/user/projects/my-web-app

Searching Notes

Search for notes about "authentication"

Search for bug-fix sessions with complex complexity

Find all notes tagged with "typescript" from the last month

Find sessions similar to ~/notes/my-project/2025-01-15_14-30-22_my-project-authentication.md

Weekly Reports

Generate a weekly report of my coding sessions

Tool Reference

capture_session_note

Capture and save a markdown note from a Claude Code session with automatic analysis.

Parameters:

Parameter	Type	Required	Description
`summary`	string	Yes	High-level summary of what was accomplished
`projectName`	string	No	Project name (used for organizing into subdirectories)
`topic`	string	No	Specific topic or feature being worked on
`commands`	array	No	List of commands executed with descriptions
`fileChanges`	array	No	Files created, modified, or deleted
`codeSnippets`	array	No	Important code snippets from the session
`tags`	array	No	Tags for categorizing the note
`workingDirectory`	string	No	Working directory (defaults to current directory)
`notesDirectory`	string	No	Custom notes directory (defaults to ~/notes or $SECOND_BRAIN_NOTES_DIR)

Command Object:

{
  command: string;        // The command that was executed
  description?: string;   // What the command does
  output?: string;        // Command output (optional)
  timestamp?: string;     // When it was executed (ISO format)
}

File Change Object:

{
  path: string;           // File path
  type: 'created' | 'modified' | 'deleted';
  description?: string;   // What changed
  diff?: string;          // Git-style diff (optional)
}

Code Snippet Object:

{
  language: string;       // Programming language for syntax highlighting
  code: string;           // The code snippet
  description?: string;   // What the code does
  filePath?: string;      // Where the code is from
}

search_notes

Search session notes with advanced filters, text search, and similarity-based discovery.

Parameters:

Parameter	Type	Required	Description
`query`	string	No	Text to search for in notes
`projectName`	string	No	Filter by project name
`tags`	array	No	Filter by tags (notes must have at least one)
`pattern`	string	No	Filter by session pattern (new-feature, bug-fix, refactoring, documentation, configuration, testing, mixed)
`complexity`	string	No	Filter by complexity level (simple, moderate, complex)
`startDate`	string	No	Filter by start date (ISO format)
`endDate`	string	No	Filter by end date (ISO format)
`similarTo`	string	No	Path to note for similarity search. Results ranked by similarity to this note.
`notesDirectory`	string	No	Custom notes directory (defaults to ~/notes or $SECOND_BRAIN_NOTES_DIR)

Text Search Examples:

Search for notes about "authentication"
Search for bug-fix sessions with complex complexity
Find all notes tagged with "typescript" from the last month

Similarity Search Examples:

Find sessions related to ~/notes/my-project/2025-01-15_14-30-22_my-project-authentication.md
Find similar sessions to my last authentication work

Combined Search:

Search for "database" sessions similar to ~/notes/my-project/2025-01-10_migration.md

Similarity is calculated using weighted Jaccard similarity:

Tags (40% weight)
Pattern matching (30% weight)
Project name (30% weight)

Results are sorted by relevance score (combined text relevance and similarity if applicable) and include project, summary, date, tags, matched tags, and file path.

generate_weekly_report

Generate a comprehensive weekly summary of all sessions.

Parameters:

Parameter	Type	Required	Description
`notesDirectory`	string	No	Custom notes directory (defaults to ~/notes or $SECOND_BRAIN_NOTES_DIR)

Example:

Generate a weekly report of my coding sessions

The report includes:

Total sessions, files changed, commands executed
Project breakdown
Work patterns distribution (🆕 New Feature, 🐛 Bug Fix, etc.)
Complexity distribution (🟢 Simple, 🟡 Moderate, 🔴 Complex)
List of all sessions with date, time, and summaries

Note Organization

Notes are saved to a centralized location (~/notes by default) and organized by project:

~/notes/
├── my-web-app/
│   ├── 2025-01-15_14-30-22_my-web-app-authentication.md
│   └── 2025-01-15_16-45-10_my-web-app-database-setup.md
├── cli-tool/
│   └── 2025-01-14_10-15-33_cli-tool-refactoring.md
└── second-brain-mcp/
    └── 2025-01-13_09-20-15_second-brain-mcp.md

Organization structure:

All notes are in one centralized directory (easier to search and backup)
Each project gets its own subdirectory
Filenames include date, time, project name, and topic
Notes without a project name go into a session/ folder

Benefits of centralized storage:

Easy to search across all projects
Simple to backup (one directory)
Works well with version control
Can be synced to cloud storage

Output Format

Generated notes include:

Header: Project name and topic
Metadata: Date, working directory, tags, Pattern (🆕/🐛/♻️/etc.), Complexity (🟢/🟡/🔴 with file count)
Summary: High-level description
Key Changes: 2-3 concise bullet points summarizing main changes
Commands Executed: All commands with outputs (collapsible)
File Changes: Organized by created/modified/deleted with descriptions
Code Snippets: With syntax highlighting and context

Example Note

# my-web-app
## Authentication

---
**Date**: 15/01/2025, 14:30:22
**Working Directory**: `/home/user/projects/my-web-app`
**Tags**: #authentication, #security, #jwt
**Pattern**: 🆕 New Feature
**Complexity**: 🟡 Moderate (3 files)
---

## Summary

Implemented user authentication system with JWT tokens and refresh token rotation

## Key Changes

- Created JWT token generation and validation
- Added authentication middleware
- Implemented login and registration endpoints

## Commands Executed

### Install authentication dependencies
```bash
npm install jsonwebtoken bcrypt

Run tests

npm run test

File Changes

Created Files

src/auth/jwt.ts - JWT token generation and validation
src/auth/routes.ts - Login and registration endpoints

Modified Files

src/server.ts - Added authentication middleware

Code Snippets

JWT validation middleware

From: src/auth/middleware.ts

export const authMiddleware = async (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) return res.status(401).json({ error: 'No token provided' });

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (error) {
    res.status(401).json({ error: 'Invalid token' });
  }
};


## Development

### Build

```bash
pnpm run build

Watch Mode

pnpm run watch

Run Locally

pnpm run dev

Testing

# Run tests
pnpm run test

# Run tests in watch mode
pnpm run test:watch

# Run tests with coverage
pnpm run test:coverage

The project has comprehensive test coverage (95%+) covering all services and utilities.

Tips

End of Session: Call the capture tool at the end of your coding session to document your work
Consistent Project Names: Use the same project name across sessions for better organization
Meaningful Summaries: Write clear summaries that you can search for later
Use Tags: Add relevant tags to make notes easier to find
Include Context: Add code snippets and file changes to provide context for future reference
File Descriptions: Add descriptions to file changes - they become Key Changes bullets in your notes

Contributing

Contributions are welcome! Please read our Contributing Guide for details on:

Setting up the development environment
Code style and conventions
Commit message format (we use Conventional Commits)
Pull request process
Running tests

Quick Start for Contributors

# Fork and clone the repository
git clone https://github.com/VoCoufi/second_brain_mcp.git
cd second_brain_mcp

# Install dependencies
pnpm install

# Run tests
pnpm run test

# Build the project
pnpm run build

Versioning

This project uses Semantic Versioning and automated releases via semantic-release. Version numbers and changelog entries are automatically generated based on commit messages.

License

MIT

Second Brain MCP Server

Features

Session Capture & Analysis

Pattern Detection: Automatically identifies session type (🆕 New Feature, 🐛 Bug Fix, ♻️ Refactoring, 📝 Documentation, ⚙️ Configuration, ✅ Testing)
Complexity Analysis: Simple file count-based classification (🟢 Simple: <3 files, 🟡 Moderate: 3-7 files, 🔴 Complex: 8+ files)
Automatic Organization: Notes organized by project into subdirectories
Rich Metadata: Captures commands, file changes, code snippets, and summaries with structured metadata
Clean Markdown: Readable format with emoji indicators and Key Changes bullets

Search & Discovery

Advanced Search: Multi-criteria filters (project, tags, pattern, complexity, date range, text query) with relevance scoring
Similarity Search: Find related sessions using Jaccard similarity across tags, patterns, and projects
Unified Search Tool: Single search_notes tool handles both text search and similarity search

Weekly Reports

Comprehensive Summaries: Statistics on sessions, files changed, and commands executed
Pattern & Complexity Distribution: Visual breakdown of work patterns and complexity levels
Project Breakdown: Sessions grouped by project
Session List: Chronological list of all sessions with summaries

Technical

No External Dependencies: Everything runs locally without API keys or external services
Metadata Caching: Fast queries with JSON metadata files
Flexible Configuration: Customize where notes are stored
TypeScript: Full type safety with comprehensive test coverage

Installation

Clone or download this repository
Install dependencies:

pnpm install

Build the TypeScript code:

pnpm run build

Configuration

Add the MCP server to your Claude Code configuration file (~/.claude/settings.local.json):

{
  "mcpServers": {
    "second-brain": {
      "command": "node",
      "args": ["/absolute/path/to/second_brain_mcp/build/index.js"]
    }
  }
}

Replace /absolute/path/to/second_brain_mcp with the actual path to this project.

Notes Directory Configuration

By default, notes are saved to ~/notes (your home directory). You can customize this in two ways:

Option 1: Environment Variable (Recommended)

Set the SECOND_BRAIN_NOTES_DIR environment variable:

export SECOND_BRAIN_NOTES_DIR=~/Documents/my-notes

Or add it to your MCP server configuration:

{
  "mcpServers": {
    "second-brain": {
      "command": "node",
      "args": ["/absolute/path/to/second_brain_mcp/build/index.js"],
      "env": {
        "SECOND_BRAIN_NOTES_DIR": "/home/username/Documents/my-notes"
      }
    }
  }
}

Option 2: Per-Tool Parameter

Pass notesDirectory parameter when calling any tool (overrides environment variable):

Please capture this session with notesDirectory: "/path/to/custom/notes"

Priority: Tool parameter > Environment variable > Default (~/notes)

Available Tools

This MCP server provides 3 focused tools for managing your session notes:

Tool	Purpose
`capture_session_note`	Capture and save detailed session notes with automatic pattern and complexity analysis
`search_notes`	Search notes with advanced filters, text search, and similarity-based discovery
`generate_weekly_report`	Generate comprehensive weekly summary reports

Usage

Once configured, you can use these tools in your Claude Code conversations:

Basic Example

Please capture this session with the summary:
"Implemented user authentication with JWT tokens"

Full Example with All Fields

Please capture this session note:

Summary: "Implemented user authentication system with JWT tokens and refresh token rotation"

Project: "my-web-app"

Topic: "authentication"

Commands executed:
- npm install jsonwebtoken bcrypt
- npm run test

File changes:
- Created: src/auth/jwt.ts - JWT token generation and validation
- Modified: src/server.ts - Added authentication middleware
- Created: src/auth/routes.ts - Login and registration endpoints

Code snippets:
- The JWT validation middleware (from src/auth/middleware.ts)
- The token generation function (from src/auth/jwt.ts)

Tags: authentication, security, jwt, backend

Working directory: /home/user/projects/my-web-app

Searching Notes

Search for notes about "authentication"

Search for bug-fix sessions with complex complexity

Find all notes tagged with "typescript" from the last month

Find sessions similar to ~/notes/my-project/2025-01-15_14-30-22_my-project-authentication.md

Weekly Reports

Generate a weekly report of my coding sessions

Tool Reference

capture_session_note

Capture and save a markdown note from a Claude Code session with automatic analysis.

Parameters:

Parameter	Type	Required	Description
`summary`	string	Yes	High-level summary of what was accomplished
`projectName`	string	No	Project name (used for organizing into subdirectories)
`topic`	string	No	Specific topic or feature being worked on
`commands`	array	No	List of commands executed with descriptions
`fileChanges`	array	No	Files created, modified, or deleted
`codeSnippets`	array	No	Important code snippets from the session
`tags`	array	No	Tags for categorizing the note
`workingDirectory`	string	No	Working directory (defaults to current directory)
`notesDirectory`	string	No	Custom notes directory (defaults to ~/notes or $SECOND_BRAIN_NOTES_DIR)

Command Object:

{
  command: string;        // The command that was executed
  description?: string;   // What the command does
  output?: string;        // Command output (optional)
  timestamp?: string;     // When it was executed (ISO format)
}

File Change Object:

{
  path: string;           // File path
  type: 'created' | 'modified' | 'deleted';
  description?: string;   // What changed
  diff?: string;          // Git-style diff (optional)
}

Code Snippet Object:

{
  language: string;       // Programming language for syntax highlighting
  code: string;           // The code snippet
  description?: string;   // What the code does
  filePath?: string;      // Where the code is from
}

search_notes

Search session notes with advanced filters, text search, and similarity-based discovery.

Parameters:

Parameter	Type	Required	Description
`query`	string	No	Text to search for in notes
`projectName`	string	No	Filter by project name
`tags`	array	No	Filter by tags (notes must have at least one)
`pattern`	string	No	Filter by session pattern (new-feature, bug-fix, refactoring, documentation, configuration, testing, mixed)
`complexity`	string	No	Filter by complexity level (simple, moderate, complex)
`startDate`	string	No	Filter by start date (ISO format)
`endDate`	string	No	Filter by end date (ISO format)
`similarTo`	string	No	Path to note for similarity search. Results ranked by similarity to this note.
`notesDirectory`	string	No	Custom notes directory (defaults to ~/notes or $SECOND_BRAIN_NOTES_DIR)

Text Search Examples:

Search for notes about "authentication"
Search for bug-fix sessions with complex complexity
Find all notes tagged with "typescript" from the last month

Similarity Search Examples:

Find sessions related to ~/notes/my-project/2025-01-15_14-30-22_my-project-authentication.md
Find similar sessions to my last authentication work

Combined Search:

Search for "database" sessions similar to ~/notes/my-project/2025-01-10_migration.md

Similarity is calculated using weighted Jaccard similarity:

Tags (40% weight)
Pattern matching (30% weight)
Project name (30% weight)

Results are sorted by relevance score (combined text relevance and similarity if applicable) and include project, summary, date, tags, matched tags, and file path.

generate_weekly_report

Generate a comprehensive weekly summary of all sessions.

Parameters:

Parameter	Type	Required	Description
`notesDirectory`	string	No	Custom notes directory (defaults to ~/notes or $SECOND_BRAIN_NOTES_DIR)

Example:

Generate a weekly report of my coding sessions

The report includes:

Total sessions, files changed, commands executed
Project breakdown
Work patterns distribution (🆕 New Feature, 🐛 Bug Fix, etc.)
Complexity distribution (🟢 Simple, 🟡 Moderate, 🔴 Complex)
List of all sessions with date, time, and summaries

Note Organization

Notes are saved to a centralized location (~/notes by default) and organized by project:

~/notes/
├── my-web-app/
│   ├── 2025-01-15_14-30-22_my-web-app-authentication.md
│   └── 2025-01-15_16-45-10_my-web-app-database-setup.md
├── cli-tool/
│   └── 2025-01-14_10-15-33_cli-tool-refactoring.md
└── second-brain-mcp/
    └── 2025-01-13_09-20-15_second-brain-mcp.md

Organization structure:

All notes are in one centralized directory (easier to search and backup)
Each project gets its own subdirectory
Filenames include date, time, project name, and topic
Notes without a project name go into a session/ folder

Benefits of centralized storage:

Easy to search across all projects
Simple to backup (one directory)
Works well with version control
Can be synced to cloud storage

Output Format

Generated notes include:

Header: Project name and topic
Metadata: Date, working directory, tags, Pattern (🆕/🐛/♻️/etc.), Complexity (🟢/🟡/🔴 with file count)
Summary: High-level description
Key Changes: 2-3 concise bullet points summarizing main changes
Commands Executed: All commands with outputs (collapsible)
File Changes: Organized by created/modified/deleted with descriptions
Code Snippets: With syntax highlighting and context

Example Note

# my-web-app
## Authentication

---
**Date**: 15/01/2025, 14:30:22
**Working Directory**: `/home/user/projects/my-web-app`
**Tags**: #authentication, #security, #jwt
**Pattern**: 🆕 New Feature
**Complexity**: 🟡 Moderate (3 files)
---

## Summary

Implemented user authentication system with JWT tokens and refresh token rotation

## Key Changes

- Created JWT token generation and validation
- Added authentication middleware
- Implemented login and registration endpoints

## Commands Executed

### Install authentication dependencies
```bash
npm install jsonwebtoken bcrypt

Run tests

npm run test

File Changes

Created Files

src/auth/jwt.ts - JWT token generation and validation
src/auth/routes.ts - Login and registration endpoints

Modified Files

src/server.ts - Added authentication middleware

Code Snippets

JWT validation middleware

From: src/auth/middleware.ts

export const authMiddleware = async (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) return res.status(401).json({ error: 'No token provided' });

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (error) {
    res.status(401).json({ error: 'Invalid token' });
  }
};


## Development

### Build

```bash
pnpm run build

Watch Mode

pnpm run watch

Run Locally

pnpm run dev

Testing

# Run tests
pnpm run test

# Run tests in watch mode
pnpm run test:watch

# Run tests with coverage
pnpm run test:coverage

The project has comprehensive test coverage (95%+) covering all services and utilities.

Tips

End of Session: Call the capture tool at the end of your coding session to document your work
Consistent Project Names: Use the same project name across sessions for better organization
Meaningful Summaries: Write clear summaries that you can search for later
Use Tags: Add relevant tags to make notes easier to find
Include Context: Add code snippets and file changes to provide context for future reference
File Descriptions: Add descriptions to file changes - they become Key Changes bullets in your notes

Contributing

Contributions are welcome! Please read our Contributing Guide for details on:

Setting up the development environment
Code style and conventions
Commit message format (we use Conventional Commits)
Pull request process
Running tests

Quick Start for Contributors

# Fork and clone the repository
git clone https://github.com/VoCoufi/second_brain_mcp.git
cd second_brain_mcp

# Install dependencies
pnpm install

# Run tests
pnpm run test

# Build the project
pnpm run build

Versioning

This project uses Semantic Versioning and automated releases via semantic-release. Version numbers and changelog entries are automatically generated based on commit messages.

License

MIT