Connect Vespper to your AI assistant

Use vespper-mcp to give an existing AI assistant access to Word documents on your computer. The package runs locally as a stdio MCP server, limits file access to directories you allow, and communicates with Vespper MCP in the cloud behind the scenes. Successful edits are saved back to the original .docx file.

Before you start

You need:

Node.js 22 or newer
A Vespper API key
An absolute path to a directory containing the documents your assistant can access

Set your API key in the environment that starts your assistant:

export VESPPER_API_KEY="sk_live_YOUR_KEY"

Connect your assistant

Replace /absolute/path/to/documents with the directory your assistant can access. Use an absolute path because MCP clients start servers without shell path expansion.

Claude Code
Cursor
Codex
Claude Desktop
Other MCP clients

Add .mcp.json to your project:

{
  "mcpServers": {
    "vespper": {
      "command": "npx",
      "args": [
        "-y",
        "vespper-mcp",
        "--allowed-directory",
        "/absolute/path/to/documents"
      ],
      "env": {
        "VESPPER_API_KEY": "${VESPPER_API_KEY}"
      }
    }
  }
}

Claude Code asks you to approve project-scoped MCP servers before using them.

Add .cursor/mcp.json to your project, or use ~/.cursor/mcp.json to make the server available in every project:

{
  "mcpServers": {
    "vespper": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "vespper-mcp",
        "--allowed-directory",
        "/absolute/path/to/documents"
      ],
      "env": {
        "VESPPER_API_KEY": "${env:VESPPER_API_KEY}"
      }
    }
  }
}

Add the server to ~/.codex/config.toml:

[mcp_servers.vespper]
command = "npx"
args = [
  "-y",
  "vespper-mcp",
  "--allowed-directory",
  "/absolute/path/to/documents",
]
env_vars = ["VESPPER_API_KEY"]

Open Settings → Developer → Edit Config, then add:

{
  "mcpServers": {
    "vespper": {
      "command": "npx",
      "args": [
        "-y",
        "vespper-mcp",
        "--allowed-directory",
        "/absolute/path/to/documents"
      ],
      "env": {
        "VESPPER_API_KEY": "sk_live_YOUR_KEY"
      }
    }
  }
}

This configuration is stored locally. Do not commit or share a configuration containing your API key.

Clients that accept the common JSON stdio configuration can use:

{
  "command": "npx",
  "args": [
    "-y",
    "vespper-mcp",
    "--allowed-directory",
    "/absolute/path/to/documents"
  ],
  "env": {
    "VESPPER_API_KEY": "sk_live_YOUR_KEY"
  }
}

Prefer your client’s secret store or environment inheritance when it supports one.

Restart your assistant after changing its MCP configuration.

Try an edit

Ask your assistant to open a document inside the allowed directory and describe the change you want:

Open /absolute/path/to/documents/contract.docx, change the payment term from 30 days to 45 days, and keep the edit as a tracked change.

The assistant can use five tools:

open_document opens one or more local .docx files.
read_document reads a page range as editable HTML.
search_document finds text without loading the entire document.
edit_document applies tracked edits and saves the updated file.
close_document saves pending changes and closes the document session.

Get started

Live-editing

Before you start

Connect your assistant

Try an edit

​Before you start

​Connect your assistant

​Try an edit

Before you start

Connect your assistant

Try an edit