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)

1. Download the latest .vsix file from Releases
2. In VSCode, open Command Palette (Cmd+Shift+P or Ctrl+Shift+P)
3. Run Extensions: Install from VSIX...
4. 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

1. Open Command Palette (Cmd+Shift+P or Ctrl+Shift+P)
2. Run MCP Bookmarks: Copy MCP Setup Command
3. Select your AI tool (Claude Code / Gemini / Codex / VSCode)
4. 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

1. Press Cmd+P (Mac) or Ctrl+P (Windows)
2. Type MCP: Open User Configuration
3. 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