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:

npx -y overseer-nvim-mcp

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 mcp add overseer -- npx -y overseer-nvim-mcp

codex mcp add overseer -- npx -y overseer-nvim-mcp

[mcp_servers.overseer]
command = "npx"
args = ["-y", "overseer-nvim-mcp"]
env_vars = ["NVIM"]

{
  "mcpServers": {
    "overseer": {
      "command": "npx",
      "args": ["-y", "overseer-nvim-mcp"]
    }
  }
}

gemini mcp add overseer npx -y overseer-nvim-mcp

{
  "mcpServers": {
    "overseer": {
      "command": "npx",
      "args": ["-y", "overseer-nvim-mcp"]
    }
  }
}

{
  "mcp": {
    "overseer": {
      "type": "local",
      "command": ["npx", "-y", "overseer-nvim-mcp"]
    }
  }
}

{
  "mcpServers": {
    "overseer": {
      "command": "npx",
      "args": ["-y", "overseer-nvim-mcp"],
      "env": { "NVIM": "${NVIM}" }
    }
  }
}

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

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 pgrep. Those approaches are structurally broken (a cwd-hash scheme cannot tell a crashed instance's stale socket from a live one and will unlink working sockets; pgrep on macOS excludes the caller's own ancestors, which is exactly the Neovim instance that matters). $NVIM sidesteps both by construction.

All user input (task names, commands, working directories) is passed as msgpack arguments and arrives in Lua as .... Nothing is ever interpolated into Lua source, so a task name cannot become code execution.

It shares your task list, so it stays out of your tasks

The task list has two writers now, and only one of them can see it. Two things keep that from biting:

• A substring matching more than one task is an error that lists the candidates and asks for a numeric id. "dev" matches a dozen names in a monorepo, and silently taking the first is how the wrong thing gets stopped.
• Tasks are tagged with who started them. overseer_list_tasks reports origin as agent or user, and overseer_stop, overseer_restart and overseer_dispose refuse a running task you started yourself unless force is passed. Finished tasks are unguarded, since removing a dead row costs nothing.

The asymmetry is on purpose. A wrong refusal costs one extra call. A wrong stop kills your dev server, loses whatever state it held, and you would have no reason to connect it to the agent.

overseer_run is for commands that do not exit on their own: dev servers, file watchers, --watch test runs. Short commands that terminate by themselves should stay on the agent's normal shell tool, where output is available in-band. Round-tripping a two-second build through start-then-poll is worse.

An empty template list is normal

overseer_list_templates returns whatever overseer's providers discover, verbatim. Most repos declare nothing runnable and return an empty list. That is a legitimate answer, not an error. This is why overseer_run takes a raw cmd as its primary path: a template-only design would be unusable in the common case.

No provider-specific knowledge lives in this server. It does not filter or rewrite results, including help-only entries some task runners expose, because doing so would mean encoding one provider's conventions into a server that must behave identically in a repo that has never heard of it.

What each entry carries:

{
  "name": "just fixture-just-generate",
  "provider": "just",
  "desc": "Generate output for a language",
  "params": [{ "name": "lang", "type": "string", "required": true }],
  "running_task_id": 128
}