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 change a document inside the allowed directory:

In contract.docx, change the payment term from 30 days to 45 days, and keep the edit as a tracked change.

Or ask it to write a new one:

Create a document called q3-memo and write a short memo about our Q3 goals.

The assistant can use four tools:

create_document creates a blank .docx in the allowed directory.
read_document reads a page range as editable HTML.
search_document finds text in one or more documents without loading them entirely.
edit_document applies edits and saves the updated file.

Paths can be absolute or relative to the allowed directory. Edits are tracked changes by default; to set their author, add "--author", "Your Name" to the server’s args.

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