rhnvrm/nvim-claudecode-mcp

nvim-claudecode-mcp

A simplified Neovim plugin that provides MCP (Model Context Protocol) server functionality with persistent state management. This plugin allows AI assistants to interact with your Neovim editor through a WebSocket-based MCP server.

Note: This is a focused fork of the excellent claudecode.nvim by Coder. See Acknowledgments for more details.

Features

• 🚀 Auto-start per repository - Remembers if you started the server in each repo and auto-starts on subsequent visits
• 🔧 11 Editor tools - File operations, selection tracking, diagnostics, diff views, and more
• 🔒 Authentication support - Optional token-based authentication
• 📊 Real-time selection tracking - Broadcasts cursor and selection changes to connected clients
• ⚡ WebSocket server - RFC 6455 compliant with JSON-RPC 2.0 protocol
• 💾 Persistent state - Remembers server preferences across Neovim sessions

Installation

Using lazy.nvim

{
  "rhnvrm/nvim-claudecode-mcp",
  dependencies = {
    "echasnovski/mini.diff", -- Optional: for better diff experience
  },
  event = "VeryLazy",
  config = function()
    require("nvim-claudecode-mcp").setup({
      port_range = { min = 3000, max = 3999 },
      auto_start = true,
      selection_tracking = true,
      diff = {
        backend = "auto", -- Uses mini.diff if available, falls back to builtin
      },
    })
  end,
}

Using packer.nvim

use {
  "rhnvrm/nvim-claudecode-mcp",
  requires = { "echasnovski/mini.diff" },
  config = function()
    require("nvim-claudecode-mcp").setup({
      diff = { backend = "auto" },
    })
  end
}

💡 Tip: See the folder for complete configuration examples, including keybindings and advanced setups.

Usage

Commands

• :MCPStart - Start the MCP server
• :MCPStop - Stop the MCP server
• :MCPToggle - Toggle the server on/off
• :MCPStatus - Show server status and repository information
• :MCPDebug - Show debug information

Basic Workflow

1. First time in a repository: Run :MCPStart to start the server
2. Connect your AI assistant to the WebSocket server (port will be shown)
3. Use AI tools - Your AI can now interact with files, selections, diagnostics, etc.
4. Next time you open the same repo - Server will auto-start automatically
5. To disable auto-start: Run :MCPStop to stop and disable auto-start for current repo

Configuration

require("nvim-claudecode-mcp").setup({
  -- Port range for the WebSocket server
  port_range = { min = 3000, max = 3999 },
  
  -- Authentication token (optional)
  auth_token = nil,
  
  -- Enable auto-start functionality
  auto_start = true,
  
  -- Enable selection tracking
  selection_tracking = true,
  
  -- Debug mode
  debug = false,
  
  -- Diff configuration (optional)
  diff = {
    backend = 'auto', -- 'auto', 'mini_diff', 'builtin'
  },
})

Diff Configuration

The plugin supports multiple diff backends for viewing file changes, automatically detecting and using the best available option.

Available Backends

• auto (default): Automatically detects and uses the best available backend
• mini_diff: Uses mini.diff for unified inline diffs
• builtin: Uses Neovim's built-in diff for side-by-side comparison

Configuration Options

diff = {
  backend = "auto", -- "auto", "mini_diff", "builtin"
}

Features by Backend

Dependencies

To use the mini_diff backend, install mini.diff:

-- With lazy.nvim
{ "echasnovski/mini.diff" }

-- With packer.nvim
use "echasnovski/mini.diff"

If mini.diff is not available, the plugin automatically falls back to the builtin backend.

Backend Options

diff = {
  backend = "auto",      -- Auto-detect (recommended)
  backend = "mini_diff", -- Force mini.diff
  backend = "builtin",   -- Force builtin vim diff
}

📁 Examples: Check and for complete configuration examples.

Available Tools

The MCP server exposes these tools to connected AI clients:

File Operations

• openFile - Open files with optional text selection
• saveDocument - Save files with unsaved changes
• checkDocumentDirty - Check if files have unsaved changes

Editor State

• getOpenEditors - List all open editor tabs
• getCurrentSelection - Get current text selection
• getLatestSelection - Get most recent selection
• getWorkspaceFolders - Get workspace folder information

Development Tools

• getDiagnostics - Get LSP diagnostics (errors, warnings)
• openDiff - Open diff views comparing file versions
• closeAllDiffTabs - Close all MCP diff tabs

Architecture

Core Components

• WebSocket Server - RFC 6455 compliant WebSocket implementation
• JSON-RPC Protocol - MCP 2.0 protocol handler
• Tools System - Modular tool registration and execution
• Selection Tracking - Real-time cursor and selection monitoring
• State Management - Persistent repository-based configuration

State Storage

The plugin stores state in ~/.local/share/nvim/nvim-claudecode-mcp/state.json:

{
  "version": "1.0.0",
  "repositories": {
    "myproject_a1b2c3d4": {
      "auto_start": true,
      "last_started": 1703123456,
      "root_path": "/home/user/projects/myproject"
    }
  },
  "global": {
    "last_auth_token": "optional-token",
    "default_port_range": { "min": 3000, "max": 3999 }
  }
}

AI Assistant Integration

Once the server is running, AI assistants can connect via WebSocket to:

ws://localhost:PORT/

With optional authentication header:

x-claude-code-ide-authorization: your-token-here

Development

Project Structure

lua/nvim-claudecode-mcp/
├── init.lua              # Main module
├── server/               # MCP server implementation
│   ├── init.lua          # Server core
│   ├── tcp.lua           # TCP server
│   ├── client.lua        # Client management  
│   ├── handshake.lua     # WebSocket handshake
│   ├── frame.lua         # WebSocket frame handling
│   └── utils.lua         # WebSocket utilities
├── tools/                # MCP tools
│   ├── init.lua          # Tools system
│   ├── open_file.lua     # File operations
│   ├── get_*.lua         # State queries
│   └── *.lua             # Other tools
└── support/              # Support modules
    ├── state.lua         # Persistent state
    └── selection.lua     # Selection tracking

Troubleshooting

Server won't start

• Check if port range is available: :MCPDebug
• Verify no other processes are using the ports
• Check Neovim version compatibility (requires Neovim 0.7+)

Auto-start not working

• Verify you're in the same directory/repository
• Check state file: ~/.local/share/nvim/nvim-claudecode-mcp/state.json
• Run :MCPStatus to see auto-start repositories

Tools not working

• Ensure LSP is running for diagnostic tools
• Check that files are actually open in buffers
• Verify selection tracking is enabled

Development & Testing

Using Nix Flake (Recommended)

The project includes a Nix flake for easy development and testing:

# Test the plugin in a controlled environment
nix run .#test

# Enter development shell with all tools
nix develop

# Just run Neovim with the plugin loaded
nix run .#nvim

# Run syntax checks
nix build .#checks.x86_64-linux.syntax-check

The development environment includes:

• Neovim with nvim-claudecode-mcp pre-configured
• Testing tools (git, curl, websocat, lua, luajit)
• Automatic plugin loading and setup

Manual Testing

1. Install the plugin in your Neovim configuration
2. Run :MCPStart in a git repository
3. Connect to the WebSocket server using a tool like websocat:

   websocat ws://localhost:3000
   

4. Send MCP protocol messages to test functionality

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test using the Nix flake: nix run .#test
5. Run syntax checks: nix flake check
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

This plugin is a focused fork of the outstanding claudecode.nvim project by Coder. The original project deserves full credit for:

• Reverse Engineering Excellence: The incredible work of reverse-engineering Claude Desktop's MCP protocol implementation
• Protocol Documentation: Clear and comprehensive protocol definitions and implementation details
• WebSocket Implementation: Robust RFC 6455 compliant WebSocket server with proper authentication
• Tool Architecture: Well-designed modular tool system for editor integration
• Original Codebase: The foundational code that made this fork possible

Why This Fork?

This fork was created with a specific use case in mind: simple, set-and-forget MCP integration for users who prefer a streamlined experience similar to Claude Code's VS Code integration.

Key Differences from Original:

• No Terminal Management: Removes terminal integration since many users (myself included) don't use Neovim's built-in terminal
• Auto-Start Focus: Emphasizes persistent state and automatic server startup per repository
• Simplified Setup: "Install and forget" philosophy - minimal configuration needed
• MCP-Only: Focuses solely on MCP server functionality without additional features

Perfect for users who:

• Don't use Neovim's terminal features
• Want Claude integration that "just works" like in VS Code
• Prefer minimal configuration and automatic behavior
• Want repository-aware persistent state

All the hard technical work - protocol reverse engineering, WebSocket implementation, tool design, and core architecture - was brilliantly executed by the original Coder team. This fork simply reorganizes that excellent foundation for a specific workflow preference.

Original Project

Please check out and star the original project: coder/claudecode.nvim

Related Projects

• claudecode.nvim - The original full-featured Claude Code integration for Neovim