Neovim MCP Server for Session Management

Overview

This repository implements an MCP (Model Context Protocol) server tailored for Neovim session management. It provides an API and tooling to save, restore, export, and share Neovim workspaces (sessions) so you can quickly move between projects, reproduce editor state, or distribute a fully configured editing environment to teammates. The server acts as a centralized store for session state and exposes operations that Neovim (or external tools) can call to manage session lifecycles.

For developers, this is useful when you want deterministic session handling across machines, automate workspace setup in CI, or integrate Neovim state with other tooling (such as language servers, workspace snapshots, or LLM-driven agents). The server follows the MCP design goals of simple, debuggable endpoints and a small surface area for integrations.

Source: https://github.com/bigcodegen/mcp-neovim-server

Features

• Save and restore complete Neovim sessions (buffers, windows, layout, cursors, optionally plugin state)
• List, rename, delete, and export/import sessions as portable archives
• HTTP API compatible with MCP-style tooling for LLM and automation integrations
• CLI client for quick local interaction
• Configurable storage backend (local filesystem by default; optional cloud/object store)
• Authentication and basic access control (token-based) for shared setups
• Hooks for Neovim plugin integration to auto-sync session state

Installation / Configuration

The repository can be run locally or deployed to a server. Below are common installation patterns—adjust to the implementation in the repo (language/runtime may vary).

Clone the repo:

git clone https://github.com/bigcodegen/mcp-neovim-server.git
cd mcp-neovim-server

Example: Python-based installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# configure via env or config file (see config.example.yaml)
export MCP_NVIM_PORT=8080
export MCP_STORAGE_PATH="$HOME/.local/share/mcp-nvim"
python -m mcp_neovim_server.main

Example: Node.js-based installation

# If the project is Node-based
npm install
cp .env.example .env
# edit .env for storage path, port, auth tokens
npm start

Configuration (common options)

# config.yaml (example)
server:
  host: "0.0.0.0"
  port: 8080

storage:
  backend: "filesystem"    # "filesystem" | "s3" | "gcs"
  path: "/var/lib/mcp-nvim"

auth:
  enabled: true
  tokens:
    - "your-long-token-here"

Run as a systemd service (example)

[Unit]
Description=MCP Neovim Server

[Service]
User=deployer
WorkingDirectory=/opt/mcp-neovim-server
ExecStart=/opt/mcp-neovim-server/.venv/bin/python -m mcp_neovim_server.main
Environment=CONFIG_PATH=/opt/mcp-neovim-server/config.yaml

[Install]
WantedBy=multi-user.target

Available Resources

The server exposes both an HTTP API and a CLI. Below are typical endpoints and commands (names may vary in the repository implementation).

HTTP API (examples)

CLI (examples)

# List sessions
mcp-nvim-cli list

# Save a session from a running Neovim instance
mcp-nvim-cli save --name "project-x" --nvim-socket /tmp/nvim1234

# Restore a session locally (downloads and unpacks)
mcp-nvim-cli restore project-x --nvim-exec nvim

# Export a session archive
mcp-nvim-cli export project-x --output project-x.mcp.tar.gz

Use Cases

• Workspace portability: Save your exact Neovim layout and buffer selection before switching machines. Restore on another machine to continue work instantly.
• Team onboarding and reproducible reviews: Share a session archive with a teammate so they open the same files and layout for pairing or code review.
• CI reproducible environments: Capture an editor state that includes generated files or temporary buffers to reproduce a debugging session in CI artifacts.
• Teaching and demos: Prepare sessions that show a sequence of files and cursor locations; students can load the same session to follow along.
• LLM-assisted coding: Combine with MCP-capable LLM agents to let models open, inspect, and modify a workspace by requesting session snapshots and restores.

Tips for Developers

• Integrate the Neovim-side plugin (or simple remote commands) to call the server APIs automatically on save/exit.
• Use token-based auth for shared servers; rotate tokens and store them in your editor config manager.
• If using cloud storage backend, set up lifecycle rules to avoid unbounded storage growth for temporary sessions.

For exact command names, runtime details, and implementation-specific flags, refer to the repository README and the included example configuration files in the project.