MCP server for AI-assisted control of Neovim via pynvim
Project description
nvim-mcp
nvim-mcp is an MCP server that lets AI assistants (Cursor, Claude, and others) control a running Neovim session: open buffers, move the cursor, run LSP actions, inspect layout, and more. It talks to Neovim over its default socket via pynvim, discovers instances automatically, and exposes four tools.
Platforms: Linux and macOS only.
Install
uv tool install nvim-mcp
Or run without installing:
uvx nvim-mcp
Quick start
- Start Neovim (it listens on an RPC socket by default).
- Set up your MCP client and agent rules — see
config/for everything you need. - The assistant can now control Neovim through 4 tools.
Tools
| Tool | Purpose |
|---|---|
nvim_send |
The universal interface. Send any ex command, Vimscript expression, or key sequence to Neovim. Three modes: command, eval, keys. |
nvim_state |
Structured snapshot: current file, cursor position, mode, window layout, modified buffers, cwd, and more. |
nvim_connect |
Connect to a Neovim instance. Auto-connects when only one exists; lists all when multiple are found. |
nvim_recipes |
Browse operation recipes by category (files, navigation, buffers, windows, marks, registers, folds, LSP). |
Multi-instance
One Neovim instance running? Tools auto-connect. Multiple? nvim_connect lists them — pick by index, socket_path, or terminal_pid. Set NVIM_SOCKET_PATH to skip discovery entirely.
Setup
See config/ for MCP client registration (Cursor, Claude Desktop, Claude CLI) and example agent rule files.
Requirements
- Python ≥ 3.10
- Linux or macOS
- Neovim with RPC socket enabled (default)
License
MIT — see LICENSE.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file nvim_mcp-0.1.1.tar.gz.
File metadata
- Download URL: nvim_mcp-0.1.1.tar.gz
- Upload date:
- Size: 10.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"25.10","id":"questing","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
204ccd5fb956a33925baa299e2636e157640a63281ab1a735ff45e1226482ca7
|
|
| MD5 |
1ff8a513e1dbd98e4505594a2548bf53
|
|
| BLAKE2b-256 |
910f7b50f49a7cca8abab19a406967b3636d7c1d882c33b9deeae82271fa3680
|
File details
Details for the file nvim_mcp-0.1.1-py3-none-any.whl.
File metadata
- Download URL: nvim_mcp-0.1.1-py3-none-any.whl
- Upload date:
- Size: 11.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"25.10","id":"questing","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
754f252b2208cd6806861083f2c665ec3d946b8aa80b7a4424ccc744456af989
|
|
| MD5 |
90f7be0d7e62744e59485607cce936e5
|
|
| BLAKE2b-256 |
0fb3c0b2fd0b32e38cdaff558df4d4bccbfd50e696a5eb5c4588227052220434
|
