nvim-mcp

AI 에이전트가 실행 중인 Neovim 세션에 직접 접근할 수 있도록 해주는 MCP 서버입니다. Neovim의 기본 msgpack-RPC 소켓을 통해 연결되므로 별도의 플러그인이 필요하지 않습니다.

Cursor, Claude Code, Codex, OpenCode 및 모든 MCP 호환 클라이언트와 함께 작동합니다.

에이전트를 Neovim에 연결하기 전에 안전하게 작업하기를 읽어주세요.

에이전트가 할 수 있는 작업

• 사용자 화면 확인 — 에디터 모드, 작업 디렉토리, 열려 있는 버퍼, 창 레이아웃, 커서 컨텍스트, 폴드, 선택 영역, 마크 및 진단 정보.

• 메모리 내 버퍼 편집 — 즉각적인 피드백과 전체 실행 취소(undo) 지원을 통한 찾기 및 바꾸기 또는 전체 재작성. 저장하기 전까지는 디스크에 아무것도 기록되지 않습니다.

• 모든 Vim 명령어 실행 — :w, :e, :vsplit, 매크로 또는 명령줄에서 입력할 수 있는 모든 작업.

• 키 입력 전송 — 탐색, 입력 모드 전환, 매핑 트리거.

• LSP 진단 쿼리 — 단일 버퍼 또는 전체 세션에 걸친 오류, 경고 및 힌트 확인.

• 하이라이트로 코드 주석 달기 — 특정 줄에 주의를 끌기 위한 색상 extmark 표시.

• 다중 인스턴스 작업 — 실행 중인 세션을 자동으로 검색하여 올바른 세션에 연결합니다. 다중 인스턴스를 참조하세요.

Neovim에서 할 수 있는 모든 작업을 에이전트도 수행할 수 있습니다. 자세한 내용은 전체 도구 참조를 확인하세요.

Related MCP server: Vigentic MCP

데모

빠른 시작

nvim-mcp는 uv(권장) 또는 Nix를 통해 실행됩니다.

Cursor 사용자: 마켓플레이스 플러그인이 검토 중입니다. 사용 가능해지면 MCP 서버와 에이전트 규칙이 함께 설치됩니다(4단계로 건너뛰어도 됩니다). 규칙을 활성화하려면 *"Connect to my Neovim instance"*와 같이 채팅을 시작하거나, 설정 → 규칙에서 규칙을 "항상(Always)"으로 설정하여 모든 턴에 적용하세요.

1. 런처 설치.

   curl -LsSf https://astral.sh/uv/install.sh | sh

   Nix를 설치하세요. flakes가 활성화되어 있어야 합니다.

2. 클라이언트에 MCP 서버 등록. Cursor 예시 (.cursor/mcp.json):

   {
     "mcpServers": {
       "nvim-mcp": {
         "command": "uvx",
         "args": ["nvim-mcp"]
       }
     }
   }

   {
     "mcpServers": {
       "nvim-mcp": {
         "command": "nix",
         "args": ["run", "github:paulburgess1357/nvim-mcp"]
       }
     }
   }

   Claude Code, Codex, Claude Desktop, OpenCode 및 기타 클라이언트는 구성 가이드를 참조하세요.

3. 에이전트 규칙 추가 — 이 단계를 건너뛰지 마세요. 규칙이 없으면 에이전트가 도구는 가지고 있지만 언제 어떻게 사용해야 할지 몰라 동작이 불안정해집니다. 설정은 구성 가이드를 참조하세요.

4. Neovim 시작 — 대부분의 Linux 시스템에서는 자동으로 Unix 소켓에서 수신 대기하며 nvim-mcp가 이를 검색합니다. 자동 검색이 작동하지 않으면 환경 변수를 참조하세요. 여러 인스턴스를 실행 중인가요? 다중 인스턴스를 참조하세요.

작동 확인

Neovim에서 파일을 열고 AI 에이전트에 다음을 붙여넣으세요:

For each step: explain what you're about to do, then do it, then tell me
what happened. Wait for me to say "next" before moving on.

1. What file am I in? Highlight the function my cursor is in.
2. Are there any diagnostics? Highlight any lines with errors or warnings.
3. Add a docstring above the function, then show me the diff.
4. Open a vertical split, write a short test for that function, and save both files.

안전하게 작업하기

도구와 에이전트 규칙은 비파괴적인 작업을 수행하도록 설계되었습니다. 편집은 메모리 내에서 발생하고, 실행 취소 기록이 보존되며, 에이전트는 버퍼 작업 위주로 유도됩니다. 하지만 LLM은 비결정적이며 Neovim API에 대한 전체 접근 권한을 가지고 있으므로 실수를 할 수 있다고 가정해야 합니다. 버전 관리가 되는 디렉토리에서 작업하세요.

요구 사항

• Linux

• Python ≥ 3.10

• Neovim ≥ 0.11 (이전 버전은 --listen 및 NVIM_ADDRESS와 함께 작동)

라이선스

MIT — LICENSE를 참조하세요.