impossiblecode/overseer-nvim-mcp

An MCP server that gives a coding agent the
same control over overseer.nvim
tasks that you have: list, tail, run, restart, stop, and dispose.
Why
Your agent's shell tool and your overseer task list are separate execution
worlds. A dev server the agent starts in its own shell is invisible in the task
list, can't be stopped from it, and orphans its process tree when the session
ends. Tasks *you* start get proper teardown. This closes that gap: the agent's
long-running commands become real overseer tasks.
Requirements
- Neovim with overseer.nvim
(tested against v2.1.0)
- Node >= 22
- An MCP client running **inside** a Neovim terminal buffer
Install
The server speaks stdio and is started by your MCP client. The command is
always the same:
The client must run **inside a Neovim terminal buffer**; that is where the
$NVIM socket it inherits comes from. Tools appear at the next session start,
since MCP servers connect at startup. If the tools never appear, the usual
cause is that $NVIM did not reach the server's environment: the server
registers nothing without it, and some clients strip the environment they
pass to servers.
Claude Code
Codex CLI
Then add one line to the generated block in ~/.codex/config.toml:
The env_vars line is required. Codex passes stdio servers a fixed whitelist
of variables (HOME, PATH, TERM and the like), $NVIM is not on it, and
without it the server registers no tools.
Codex also won't reach for the server on its own; see
Getting your agent to actually use it.
Antigravity CLI
In ~/.gemini/config/mcp_config.json:
That user-global file is the one to use: the CLI's non-interactive print mode
(agy -p) loads MCP servers from it and from nowhere else; a workspace-level
.agents/mcp_config.json is silently ignored there.
Antigravity also won't reach for the server on its own; see
Getting your agent to actually use it.
Gemini CLI
Or in settings.json:
opencode
In opencode.json:
mcphub.nvim (codecompanion.nvim, avante.nvim)
In mcphub's servers config:
The env block is required: mcp-hub does not pass its own environment to the
servers it spawns, so without it the server sees no $NVIM and registers no
tools. The server operates on the Neovim instance that started the hub. A hub
started outside Neovim has no $NVIM to forward, and mcp-hub reports this
server as disconnected with Variable 'NVIM' not found.
Using with LazyVim
LazyVim ships an overseer.nvim extra.
Enable it with :LazyExtras (select editor.overseer), restart Neovim, then
add the server to your MCP client as above. Nothing else is needed; the server
talks to whatever overseer configuration you already have.
Tools
| Tool | Purpose |
|------|---------|
| overseer_list_tasks | Tasks with id, name, status, exit_code, cmd, cwd, timings, origin |
| overseer_list_templates | Templates in a directory (npm, go-task, make, just, VS Code) with provider, desc, params |
| overseer_tail | A task's output, with status; can block until a pattern appears |
| overseer_run | Start a long-running command: a raw cmd array, or a template with params |
| overseer_restart | Restart a task by id or name substring |
| overseer_stop | Stop a running task |
| overseer_dispose | Stop and remove a task from the list |
The last three take force, and refuse a running task you started without it.
Tasks are addressed by numeric id or a case-insensitive name substring, so an
agent can say "dev" instead of tracking ids.
How it works
The transport is $NVIM, the RPC socket Neovim exports to every process it
spawns in a terminal buffer. Your MCP client inherits it, and this server, as a
child of that client, inherits it in turn.
Everything else follows from that:
- With **$NVIM set**, the server registers seven tools, each one
nvim_exec_lua against overseer over msgpack-RPC.
- With **$NVIM unset**, it registers nothing and gets out of the way. Running
outside Neovim is a no-op rather than an error.
There is no socket discovery: no cwd hashing, no lsof, no