MCP Bookmarks

Code bookmarks extension for VSCode with MCP (Model Context Protocol) integration, allowing AI assistants to annotate and explain your codebase.

Features

MCP Integration: Provides MCP tools for AI assistants (Claude Code, Gemini, etc.) to create and manage bookmarks programmatically
AI Assistant Support: AI can analyze your code and create organized bookmarks to explain architecture, flows, and key components
Manual Management: Full support for creating, editing, and organizing bookmarks without AI
Hierarchical Bookmarks: Create parent-child bookmark relationships to represent call chains and code flows
Grouped Organization: Bookmarks are organized into groups by topic, feature, or analysis session
Category System: 4 built-in categories (entry-point, core-logic, issue, note) for clear organization
Markdown Link Support: Cross-reference code locations with clickable links in bookmark descriptions
Rich Sidebar: Interactive webview with tree/nested view modes, search, and filtering
Editor Integration: Inline gutter icons, hover previews, and CodeLens support
Quick Navigation: Jump to bookmarked locations, navigate between bookmarks with keyboard shortcuts
Export & Share: Export bookmarks to Markdown, store in .vscode/mcp-bookmarks.json for version control

Installation

Method 1: Install from VSIX (Recommended)

Download the latest .vsix file from Releases
In VSCode, open Command Palette (Cmd+Shift+P or Ctrl+Shift+P)
Run Extensions: Install from VSIX...
Select the downloaded .vsix file

Method 2: Install from Source

# Clone repository
git clone https://github.com/linonon/mcp-bookmarks.git
cd mcp-bookmarks

# Install dependencies and build
npm install
npm run compile

# Package as VSIX
npm run package

# Install the generated .vsix file
code --install-extension mcp-bookmarks-*.vsix

MCP Configuration

After installing the extension, configure MCP integration for your AI tool.

Quick Setup

Open Command Palette (Cmd+Shift+P or Ctrl+Shift+P)
Run MCP Bookmarks: Copy MCP Setup Command
Select your AI tool (Claude Code / Gemini / Codex / VSCode)
The command will be copied to your clipboard

For Claude Code Users

Run this command in your terminal (generated by the extension):

claude mcp add -s user mcp-bookmarks -- node "~/.vscode/mcp-bookmarks-launcher.js"

Or manually configure in .claude/mcp.json:

{
  "mcpServers": {
    "mcp-bookmarks": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/.vscode/mcp-bookmarks-launcher.js"],
      "description": "MCP Bookmarks - Code annotation and navigation"
    }
  }
}

For Gemini Users

Run this command in your terminal (generated by the extension):

gemini mcp add -s user mcp-bookmarks node "~/.vscode/mcp-bookmarks-launcher.js"

For VSCode MCP Extension Users

Press Cmd+P (Mac) or Ctrl+P (Windows)
Type MCP: Open User Configuration
Add the following configuration:

{
  "mcpServers": {
    "mcp-bookmarks": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/.vscode/mcp-bookmarks-launcher.js"]
    }
  }
}

For Codex Users

Paste this snippet into ~/.codex/config.toml:

[mcp_servers."mcp-bookmarks"]
command = "node"
args = ["/Users/YOUR_USERNAME/.vscode/mcp-bookmarks-launcher.js"]

Note: Use the Copy MCP Setup Command to get the correct path automatically!

Usage

Complete Setup Flow

Step 1: Install Extension

# Download .vsix from GitHub Releases
# Then in VSCode Command Palette:
Extensions: Install from VSIX...

Step 2: Configure MCP (Automatic)

# In VSCode Command Palette:
MCP Bookmarks: Copy MCP Setup Command

# Select your AI tool (Claude Code / Gemini / Codex / VSCode)
# Copy the generated command

# For Claude Code, run in terminal:
claude mcp add -s user mcp-bookmarks -- node "~/.vscode/mcp-bookmarks-launcher.js"

# For Gemini, run in terminal:
gemini mcp add -s user mcp-bookmarks node "~/.vscode/mcp-bookmarks-launcher.js"

# For VSCode MCP, paste the path into User Configuration

Step 3: Start Using

Now your AI assistant can create bookmarks in your codebase!

Available MCP Tools

create_group - Create a bookmark group
add_bookmark - Add a bookmark to a group
batch_add_bookmarks - Add multiple bookmarks at once
list_groups - List all groups
list_bookmarks - List bookmarks with filters
get_group - Get group details with all bookmarks
get_bookmark - Get single bookmark details
update_group - Update group info
update_bookmark - Update bookmark properties
remove_group - Delete a group and its bookmarks
remove_bookmark - Delete a single bookmark
clear_all_bookmarks - Clear all data (requires confirmation)

For Users

Commands:

MCP Bookmarks: Refresh - Refresh the bookmark tree
MCP Bookmarks: Add Bookmark Here - Manually add a bookmark at cursor
MCP Bookmarks: Create Group - Create a new bookmark group
MCP Bookmarks: Edit Group - Edit group title and description
MCP Bookmarks: Rename Group - Quick rename a group (F2)
MCP Bookmarks: Delete Group - Delete a group and its bookmarks
MCP Bookmarks: Edit Bookmark - Edit bookmark properties
MCP Bookmarks: Delete Bookmark - Delete a bookmark
MCP Bookmarks: Move to Group... - Move bookmark to another group
MCP Bookmarks: Move Bookmark Up/Down - Reorder bookmarks within group
MCP Bookmarks: Search Bookmarks - Search through all bookmarks
MCP Bookmarks: Export as Markdown - Export bookmarks to markdown
MCP Bookmarks: Toggle View Mode - Switch between group/file view
MCP Bookmarks: Expand All - Expand all tree nodes
MCP Bookmarks: Collapse All - Collapse all tree nodes

Configuration

Setting	Default	Description
`mcpBookmarks.mcpPort`	3333	MCP Server port
`mcpBookmarks.showInlineDecorations`	true	Show bookmark icons in gutter
`mcpBookmarks.viewMode`	"group"	View mode: "group" or "file"
`mcpBookmarks.quickAddMode`	"simple"	Quick add mode: "full" (all options) or "simple" (title only)
`mcpBookmarks.defaultCategory`	"explanation"	Default category for new bookmarks
`mcpBookmarks.confirmBeforeDelete`	true	Show confirmation before deleting

Data Storage

Bookmarks are stored in .vscode/mcp-bookmarks.json within your workspace. This file can be committed to version control to share bookmarks with your team.

Development

# Install dependencies
npm install

# Watch mode (auto-recompile)
npm run watch

# Compile once
npm run compile

# Package extension
npm run package

# Lint
npm run lint

License

MIT

MCP Bookmarks

Code bookmarks extension for VSCode with MCP (Model Context Protocol) integration, allowing AI assistants to annotate and explain your codebase.

Features

MCP Integration: Provides MCP tools for AI assistants (Claude Code, Gemini, etc.) to create and manage bookmarks programmatically
AI Assistant Support: AI can analyze your code and create organized bookmarks to explain architecture, flows, and key components
Manual Management: Full support for creating, editing, and organizing bookmarks without AI
Hierarchical Bookmarks: Create parent-child bookmark relationships to represent call chains and code flows
Grouped Organization: Bookmarks are organized into groups by topic, feature, or analysis session
Category System: 4 built-in categories (entry-point, core-logic, issue, note) for clear organization
Markdown Link Support: Cross-reference code locations with clickable links in bookmark descriptions
Rich Sidebar: Interactive webview with tree/nested view modes, search, and filtering
Editor Integration: Inline gutter icons, hover previews, and CodeLens support
Quick Navigation: Jump to bookmarked locations, navigate between bookmarks with keyboard shortcuts
Export & Share: Export bookmarks to Markdown, store in .vscode/mcp-bookmarks.json for version control

Installation

Method 1: Install from VSIX (Recommended)

Download the latest .vsix file from Releases
In VSCode, open Command Palette (Cmd+Shift+P or Ctrl+Shift+P)
Run Extensions: Install from VSIX...
Select the downloaded .vsix file

Method 2: Install from Source

# Clone repository
git clone https://github.com/linonon/mcp-bookmarks.git
cd mcp-bookmarks

# Install dependencies and build
npm install
npm run compile

# Package as VSIX
npm run package

# Install the generated .vsix file
code --install-extension mcp-bookmarks-*.vsix

MCP Configuration

After installing the extension, configure MCP integration for your AI tool.

Quick Setup

Open Command Palette (Cmd+Shift+P or Ctrl+Shift+P)
Run MCP Bookmarks: Copy MCP Setup Command
Select your AI tool (Claude Code / Gemini / Codex / VSCode)
The command will be copied to your clipboard

For Claude Code Users

Run this command in your terminal (generated by the extension):

claude mcp add -s user mcp-bookmarks -- node "~/.vscode/mcp-bookmarks-launcher.js"

Or manually configure in .claude/mcp.json:

{
  "mcpServers": {
    "mcp-bookmarks": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/.vscode/mcp-bookmarks-launcher.js"],
      "description": "MCP Bookmarks - Code annotation and navigation"
    }
  }
}

For Gemini Users

Run this command in your terminal (generated by the extension):

gemini mcp add -s user mcp-bookmarks node "~/.vscode/mcp-bookmarks-launcher.js"

For VSCode MCP Extension Users

Press Cmd+P (Mac) or Ctrl+P (Windows)
Type MCP: Open User Configuration
Add the following configuration:

{
  "mcpServers": {
    "mcp-bookmarks": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/.vscode/mcp-bookmarks-launcher.js"]
    }
  }
}

For Codex Users

Paste this snippet into ~/.codex/config.toml:

[mcp_servers."mcp-bookmarks"]
command = "node"
args = ["/Users/YOUR_USERNAME/.vscode/mcp-bookmarks-launcher.js"]

Note: Use the Copy MCP Setup Command to get the correct path automatically!

Usage

Complete Setup Flow

Step 1: Install Extension

# Download .vsix from GitHub Releases
# Then in VSCode Command Palette:
Extensions: Install from VSIX...

Step 2: Configure MCP (Automatic)

# In VSCode Command Palette:
MCP Bookmarks: Copy MCP Setup Command

# Select your AI tool (Claude Code / Gemini / Codex / VSCode)
# Copy the generated command

# For Claude Code, run in terminal:
claude mcp add -s user mcp-bookmarks -- node "~/.vscode/mcp-bookmarks-launcher.js"

# For Gemini, run in terminal:
gemini mcp add -s user mcp-bookmarks node "~/.vscode/mcp-bookmarks-launcher.js"

# For VSCode MCP, paste the path into User Configuration

Step 3: Start Using

Now your AI assistant can create bookmarks in your codebase!

Available MCP Tools

create_group - Create a bookmark group
add_bookmark - Add a bookmark to a group
batch_add_bookmarks - Add multiple bookmarks at once
list_groups - List all groups
list_bookmarks - List bookmarks with filters
get_group - Get group details with all bookmarks
get_bookmark - Get single bookmark details
update_group - Update group info
update_bookmark - Update bookmark properties
remove_group - Delete a group and its bookmarks
remove_bookmark - Delete a single bookmark
clear_all_bookmarks - Clear all data (requires confirmation)

For Users

Commands:

MCP Bookmarks: Refresh - Refresh the bookmark tree
MCP Bookmarks: Add Bookmark Here - Manually add a bookmark at cursor
MCP Bookmarks: Create Group - Create a new bookmark group
MCP Bookmarks: Edit Group - Edit group title and description
MCP Bookmarks: Rename Group - Quick rename a group (F2)
MCP Bookmarks: Delete Group - Delete a group and its bookmarks
MCP Bookmarks: Edit Bookmark - Edit bookmark properties
MCP Bookmarks: Delete Bookmark - Delete a bookmark
MCP Bookmarks: Move to Group... - Move bookmark to another group
MCP Bookmarks: Move Bookmark Up/Down - Reorder bookmarks within group
MCP Bookmarks: Search Bookmarks - Search through all bookmarks
MCP Bookmarks: Export as Markdown - Export bookmarks to markdown
MCP Bookmarks: Toggle View Mode - Switch between group/file view
MCP Bookmarks: Expand All - Expand all tree nodes
MCP Bookmarks: Collapse All - Collapse all tree nodes

Configuration

Setting	Default	Description
`mcpBookmarks.mcpPort`	3333	MCP Server port
`mcpBookmarks.showInlineDecorations`	true	Show bookmark icons in gutter
`mcpBookmarks.viewMode`	"group"	View mode: "group" or "file"
`mcpBookmarks.quickAddMode`	"simple"	Quick add mode: "full" (all options) or "simple" (title only)
`mcpBookmarks.defaultCategory`	"explanation"	Default category for new bookmarks
`mcpBookmarks.confirmBeforeDelete`	true	Show confirmation before deleting

Data Storage

Bookmarks are stored in .vscode/mcp-bookmarks.json within your workspace. This file can be committed to version control to share bookmarks with your team.

Development

# Install dependencies
npm install

# Watch mode (auto-recompile)
npm run watch

# Compile once
npm run compile

# Package extension
npm run package

# Lint
npm run lint

License

MIT