@viewert/mcp

MCP server for Viewert — expose your Librams (AI context collections) to any MCP-compatible AI client.

What it does

Connects Claude Desktop, Cursor, Windsurf, or any MCP client to your Viewert Librams. Each Libram is a curated collection of Vellums (notes/documents) that you've marked as available for AI context.

Setup

Option A — One-command setup (recommended)

npx --package=@viewert/mcp viewert-mcp-setup

Or if you already have the package installed globally:

viewert-mcp-setup

The interactive wizard will:

• Install the package globally with the correct binary path
• Verify your API key against your account
• Auto-detect Claude Desktop, Cursor, and Windsurf
• Write the config for whichever clients you choose — without overwriting your other MCP servers
• Print the exact restart steps for each client

Option B — Manual setup

1. Get an API key

Go to Settings → API Keys on viewert.com and create a key. Copy it — it's shown only once.

2. Install the package globally

npm install -g @viewert/mcp

Then find the installed binary path — you'll need this for your config:

which viewert-mcp
# e.g. /usr/local/bin/viewert-mcp

Why global install? MCP clients like Claude Desktop launch the server as a subprocess and may not propagate environment variables correctly when using npx. A global install with an absolute binary path is the most reliable approach.

3. Add to your MCP client config

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "viewert": {
      "command": "/usr/local/bin/viewert-mcp",
      "args": [],
      "env": {
        "VIEWERT_API_KEY": "vwt_your_key_here"
      }
    }
  }
}

Replace /usr/local/bin/viewert-mcp with the path from which viewert-mcp.

Cursor / Windsurf (.cursor/mcp.json or .windsurf/mcp.json in your project):

{
  "mcpServers": {
    "viewert": {
      "command": "/usr/local/bin/viewert-mcp",
      "args": [],
      "env": {
        "VIEWERT_API_KEY": "vwt_your_key_here"
      }
    }
  }
}

4. Restart your AI client

Claude Desktop: Right-click the Claude icon in the menu bar → Quit (closing the window is not enough). Reopen Claude. A hammer icon in the toolbar confirms MCP tools are active.

Cursor / Windsurf: Run Reload Window from the command palette (Cmd+Shift+P).

Tools

| Tool | Description | |------|-------------| | list_librams | List all Librams in your account with names and IDs | | get_libram_context | Fetch all AI-enabled Vellums from a Libram as markdown | | get_libram_context_json | Fetch AI-enabled Vellums as structured JSON (id, title, content) |

Environment variables

| Variable | Required | Default | |----------|----------|---------| | VIEWERT_API_KEY | ✅ Yes | — | | VIEWERT_API_URL | No | https://www.viewert.com/api |

Example usage in Claude

"Load my Project Notes Libram and summarise the key points."

Claude will call list_librams to find the ID, then get_libram_context to pull the content — all inline in the conversation.