Neovim MCP Server

1# Neovim MCP Server
2 
3[![codecov](https://codecov.io/gh/linw1995/nvim-mcp/graph/badge.svg?token=OFWOKQQFSD)](https://codecov.io/gh/linw1995/nvim-mcp)
4![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/linw1995/nvim-mcp/CI.yaml)
5 
6A Model Context Protocol (MCP) server that provides seamless integration with
7Neovim instances, enabling AI assistants to interact with your editor through
8connections and access diagnostic information via structured resources.
9Supports both stdio and HTTP server transport modes for different integration
10scenarios.
11 
12## Features
13 
14- **Multi-Connection Support**: Manage multiple concurrent Neovim instances
15- **LSP Integration**: Complete LSP workflow with code actions, hover, and diagnostics
16- **Universal Document Identifier**: Work with files by buffer ID, relative path,
17  or absolute path
18- **MCP Resources**: Structured diagnostic data via connection-aware URI schemes
19- **Multi-Transport Support**: Both stdio and HTTP server transport modes
20- **Dynamic Tool System** ⚠️ **(Experimental)**: User-extensible custom tools
21- **Plugin Integration**: Automatic setup through Neovim plugin
22 
23## Installation
24 
25### Use Cargo install from crates.io
26 
27```bash
28cargo install nvim-mcp
29```
30 
31### Using Nix
32 
33```bash
34nix profile install github:linw1995/nvim-mcp#nvim-mcp
35```
36 
37### From Source
38 
39```bash
40git clone https://github.com/linw1995/nvim-mcp.git && cd nvim-mcp
41cargo install --path .
42```
43 
44## Usage Cases Collection
45 
46<!-- markdownlint-configure-file
47{
48  "no-inline-html": false
49}
50-->
51 
52<video
53  src="https://github.com/user-attachments/assets/6946ee1c-42ac-4313-ae10-ca92a4dd0ab7"
54  style="max-height:640px; min-height: 200px">
55</video>
56 
57- LSP Hover Translation (From [#85](https://github.com/linw1995/nvim-mcp/discussions/85))
58- Diagnostic Analysis and Code Fixes (From [#10](https://github.com/linw1995/nvim-mcp/discussions/10))
59- Smart Context Retrieval (From [#86](https://github.com/linw1995/nvim-mcp/discussions/86))
60- And more in [Discussions](https://github.com/linw1995/nvim-mcp/discussions)
61 
62## Quick Start
63 
64### 1. Setup Neovim Integration
65 
66With a plugin manager like `lazy.nvim`:
67 
68```lua
69return {
70    "linw1995/nvim-mcp",
71    build = "cargo install --path .",
72    opts = {},
73}
74```
75 
76### 2. Configure `claude` or other MCP clients
77 
78```bash
79# Auto-connect to current project Neovim instances (recommended)
80claude mcp add -s local nvim -- nvim-mcp --log-file . \
81  --log-level debug --connect auto
82 
83# Analyze diagnostics in current Neovim instance
84claude "analyze @nvim:nvim-diagnostics://"
85```
86 
87## Documentation
88 
89For detailed information, see:
90 
91- **[Usage Guide](docs/usage.md)**: Detailed usage workflows, CLI options,
92  and transport modes
93- **[Tools Reference](docs/tools.md)**: Complete reference for all 26 MCP tools
94- **[Resources](docs/resources.md)**: MCP resources and URI schemes
95- **[Development](docs/development.md)**: Development setup, testing,
96  and contributing
97 
98## Development
99 
100Basic development setup:
101 
102```bash
103# Enter development shell
104nix develop .
105 
106# Run tests
107cargo test -- --show-output
108 
109# Build and run
110cargo run -- --connect auto
111```
112 
113See [Development Guide](docs/development.md) for complete setup instructions,
114testing procedures, and contribution guidelines.
115