nvim-mcp: AI 에이전트에게 Neovim 세션에 대한 일급 접근 권한을 제공하는 MCP 서버

AI 에이전트에게 실행 중인 Neovim 세션에 대한 일급 접근 권한 (first-class access)을 제공하는 MCP 서버입니다. 별도의 플러그인 없이 Neovim의 네이티브 msgpack-RPC 소켓을 통해 연결됩니다.

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

에이전트를 Neovim에 연결하기 전에, '안전하게 작업하기 (Working safely)'를 읽어주세요.

사용자가 보는 것을 그대로 확인— 에디터 모드, 작업 디렉토리, 열려 있는 버퍼 (buffers), 창 레이아웃, 커서 컨텍스트, 폴드 (folds), 선택 영역, 마크 (marks) 및 진단 (diagnostics) 정보를 확인합니다. 메모리 내에서 버퍼 편집— 즉각적인 피드백과 완전한 실행 취소 (undo) 지원을 통해 찾기 및 바꾸기 또는 전체 재작성을 수행합니다. 저장하기 전까지는 디스크에 아무것도 영향을 주지 않습니다. 모든 Vim 명령 실행— :w, :e, :vsplit, 매크로 또는 명령줄에 입력할 수 있는 그 어떤 것이든 실행할 수 있습니다. 키 입력 전송— 탐색, 삽입 모드 진입, 매핑 (mappings) 트리거 등을 수행합니다. LSP 진단 쿼리— 하나의 버퍼 또는 전체 세션에 걸친 에러, 경고 및 힌트를 확인합니다. 하이라이트 및 가상 텍스트로 코드 주석 달기— 버퍼의 실제 내용에는 영향을 주지 않는 색상 라인 하이라이트와 인라인/상단/하단 텍스트 노트를 사용합니다. 여러 인스턴스와 함께 작업— 실행 중인 세션을 자동으로 검색하고 올바른 세션에 연결합니다. 여러 인스턴스를 확인하세요.

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

두 개의 터미널에서 nvim-mcp 사용하기

demo1_two_terminals.mp4

Neovim 내부의 터미널에서 nvim-mcp 사용하기

demo2_agent_in_nvim.mp4

하나의 Neovim 인스턴스에서 Claude와 Cursor의 협업

multi-agent-compressed.mp4

Cursor에서 nvim-mcp 사용하기

cursor_example.mp4

여러 개의 Neovim 인스턴스

multi-instance1-web.mp4

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

Cursor 사용자: Marketplace 플러그인이 검토 대기 중입니다. 사용 가능해지면 MCP 서버와 에이전트 규칙 (agent rule)을 함께 설치합니다 (4단계로 건너뛸 수 있습니다). 규칙을 활성화하려면 "Connect to my Neovim instance"와 같은 문구로 채팅을 시작하거나, Settings → Rules에서 규칙을 "Always"로 설정하여 매 턴마다 적용되도록 하세요.

**런처 설치하기. uvcurl -LsSf https://astral.sh/uv/install.sh | sh

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

uv 사용 시
{ "mcpServers": { "nvim-mcp": { "command": "uvx", "args": ["nvim-mcp"] } } }

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

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

에이전트 규칙 추가하기 — 이 단계를 건너뛰지 마세요. 규칙이 없으면 에이전트가 도구(tools)는 가지고 있지만, 그것을 언제 어떻게 사용해야 하는지 알지 못하므로 동작이 불안정해질 수 있습니다. 설정을 위해 설정 가이드를 참조하세요.

Neovim 시작하기— 대부분의 Linux 시스템에서는 자동으로 Unix 소켓(Unix socket)에서 대기하며 nvim-mcp에 의해 발견됩니다. 자동 발견(auto-discovery)이 작동하지 않으면 환경 변수(environment variables)를 참조하세요. 여러 인스턴스를 실행 중인가요? 여러 인스턴스(multiple instances) 섹션을 참조하세요.

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

각 단계마다: 당신이 무엇을 하려는지 설명하고, 실행한 다음, 어떤 일이 일어났는지 나에게 알려주세요. 다음 단계로 넘어가기 전에 내가 "next"라고 말할 때까지 기다려주세요.
1. 내가 어떤 파일에 있나요? 내 커서가 위치한 함수를 하이라이트(Highlight) 해주세요.
...

도구와 에이전트 규칙은 비파괴적 작업(non-destructive operations)을 사용하도록 설계되었습니다. 즉, 편집은 메모리 내에서 이루어지고, 실행 취소(undo) 기록이 보존되며, 에이전트는 버퍼 작업(buffer operations)을 수행하도록 유도됩니다. 하지만 LLM(Large Language Models)은 비결정론적(non-deterministic)이며 Neovim의 API에 대한 완전한 접근 권한을 가지므로, 실수를 할 수 있다고 가정해야 합니다. 버전 관리(version-controlled)가 되는 디렉토리에서 작업하세요.

• Linux
• Python ≥ 3.10
• Neovim ≥ 0.11 (--listen 및 NVIM_ADDRESS를 사용하면 이전 버전도 작동합니다)

MIT — LICENSE를 참조하세요.