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.

Atm, I mainly use this for getting the agent to show me files/lines in Vim.

Sometimes, I use it for showing selected regions to the agent.

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

Options

Tools

The server exposes the following tools to MCP clients:

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.

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