vim-mcp-server

An MCP (Model Context Protocol) server embedded in Vim. It exposes tools over HTTP that let MCP-compatible clients — such as AI coding agents — read and modify buffers, move the cursor, retrieve visual selections, manage quickfix and location lists, open side-by-side diffs (including git diffs computed inside Vim), read message history, and run Ex commands.

Requirements

• Vim compiled with +python3

Installation

Use your preferred plugin manager.

vim-plug

Plug 'breggles/vim-mcp-server'

Vundle

Plugin 'breggles/vim-mcp-server'

Manual

Clone the repository into your Vim packages directory:

git clone https://github.com/breggles/vim-mcp-server.git \
    ~/.vim/pack/plugins/start/vim-mcp-server

Usage

Start the server

In Vim, run:

:McpServerStart

Auto-start the server on Vim launch by adding this to your vimrc:

let g:mcp_server_autostart = 1

MCP Client Configuration

Point your MCP client at http://127.0.0.1:8765/mcp (or whichever port you chose).

For example, for opencode add the server to your opencode.jsonc:

"mcp": {
  "vim": {
    "type": "remote",
    "url": "http://localhost:8765/mcp",
    "enabled": true
  }
}

Commands

Command	Description
:McpServerStart [port]	Start the server (default port 8765)
:McpServerStop	Stop the server
:McpServerStatus	Print server status and URL

Options

Variable	Default	Description
g:mcp_server_port	8765	Port the server listens on
g:mcp_server_autostart	0	Start the server automatically on VimEnter
g:mcp_server_allow_execute	0	Enable the execute_command tool
g:mcp_server_allow_save	0	Enable the save_buffer tool
g:mcp_server_allow_edit	0	Enable the edit_buffer tool

Tools

The server exposes the following tools to MCP clients:

Tool	Description
list_buffers	List all open buffers
get_buffer	Read buffer contents (optionally a line range)
edit_buffer	Replace, insert, or delete lines in a buffer
open_file	Open a file via :edit
save_buffer	Save a buffer via :write (opt-in, see above)
close_buffer	Close a buffer via :bdelete
get_cursor	Get current cursor position
set_cursor	Move cursor to a line and column
get_visual_selection	Get the current visual selection, if any
execute_command	Run an arbitrary Ex command (opt-in, see above)
get_quickfix_list	Get the current quickfix list entries
set_quickfix_list	Set the quickfix list
get_location_list	Get the location list for the current window
set_location_list	Set the location list for the current window
get_messages	Get Vim's message history (:messages output)
show_diff	Open a side-by-side diff view in a new tab (files or content)
show_git_diff	Open a side-by-side git diff in a new tab; git computes both sides inside Vim

When a tool accepts a buffer argument it can be specified by number (buffer_id) or by file path (buffer_path). When both are omitted, the current buffer is used.

show_git_diff

Opens a side-by-side diff view in a new tab for a git-tracked file. The MCP client only sends the file path and (optionally) two refs; git fetches the contents of both sides inside Vim. Prefer this over show_diff whenever comparing git revisions, the index, or the working tree — it avoids the client having to pre-fetch and send the full file contents.

Parameters:

Param	Type	Required	Default	Notes
path	string	yes	-	Absolute path to the file. May refer to either the pre- or post-rename name.
ref_a	string	no	"HEAD"	Left-side revision. Empty string means working tree on disk.
ref_b	string	no	""	Right-side revision. Empty string means working tree on disk.
staged	boolean	no	false	Convenience for HEAD vs index. Mutually exclusive with explicit ref_a / ref_b.

Behaviour notes:

• The repo root is auto-discovered from path; the file must live inside a git repository.
• Each buffer's filetype is detected by Vim's own :filetype detect, using the file's name at the corresponding side, so a renamed file gets correct highlighting on each side independently. Requires Vim's filetype plugins to be enabled (:filetype on, which is the default).
• Rename detection (git diff -M) is enabled, so a file renamed between the two revisions is followed across sides.
• If a side does not contain the file (e.g. an added or deleted file), that buffer is shown empty and its label is marked (missing).
• Each call opens its own new tab. Call multiple times for multiple diffs.

For non-git diffs (comparing arbitrary buffers, files, or generated content) use show_diff instead.

OpenCode Plan Mode

By default, OpenCode's plan mode disables all MCP tools. To allow read-only vim tools in plan mode, add the following to your opencode.jsonc:

{
  "agent": {
    "plan": {
      "tools": {
        "vim_*": false,
        "vim_list_buffers": true,
        "vim_get_buffer": true,
        "vim_get_cursor": true,
        "vim_get_visual_selection": true,
        "vim_open_file": true,
        "vim_set_cursor": true,
        "vim_get_quickfix_list": true,
        "vim_set_quickfix_list": true,
        "vim_get_location_list": true,
        "vim_set_location_list": true,
        "vim_get_messages": true,
        "vim_show_diff": true,
        "vim_show_git_diff": true
      }
    }
  }
}

This disables all vim_* tools first, then re-enables specific ones. Adjust the list to suit your workflow.

Development

To work on the plugin without installing it, clone the repository and add it to Vim's runtime path:

set rtp+=~/path/to/vim-mcp-server

Add this to your vimrc or run it manually. Changes take effect the next time Vim is started.

Generate the help tags with:

:helptags ~/path/to/vim-mcp-server/doc

License

MIT