Skip to main content
@shelv/mcp is an MCP server that exposes Shelv shelf operations as tools. Any MCP-compatible client — Claude Code, Claude Desktop, Cursor, Windsurf — can list shelves, read files, search content, and optionally create and hydrate shelves. Supports stdio (default) and HTTP transports. Source code: github.com/shelv-dev/shelv-mcp

​
Quick setup

Run the server with npx: 
npx @shelv/mcp
Or install globally: 
npm install -g @shelv/mcp
shelv-mcp

​
Claude Code

claude mcp add shelv -- npx @shelv/mcp
Set your API key in the environment where Claude Code runs: 
export SHELV_API_KEY="sk_..."
Don’t have an API key yet? See the Authentication guide.

​
Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json): 
{
  "mcpServers": {
    "shelv": {
      "command": "npx",
      "args": ["@shelv/mcp"],
      "env": {
        "SHELV_API_KEY": "sk_..."
      }
    }
  }
}

​
Cursor

Add to .cursor/mcp.json in your project root: 
{
  "mcpServers": {
    "shelv": {
      "command": "npx",
      "args": ["@shelv/mcp"],
      "env": {
        "SHELV_API_KEY": "sk_..."
      }
    }
  }
}

​
Available tools

ToolDescriptionMode
list_shelvesList shelves available to the authenticated userRead
get_shelf_treeGet the full file tree and file contents for a shelfRead
read_shelf_fileRead a single file from a shelfRead
search_shelfSearch for text across files in a shelfRead
create_shelfUpload a local PDF and create a shelfWrite
hydrate_shelfDownload and write shelf files into a local directoryWrite

​
Write tools

Write tools (create_shelf and hydrate_shelf) are disabled by default. Enable them by setting: 
export SHELV_MCP_ENABLE_WRITE_TOOLS=true
When disabled, only the four read tools are registered with the MCP server.

​
Environment variables

VariableDefaultDescription
SHELV_API_KEY—API key for authentication (required)
SHELV_MCP_TRANSPORTstdioTransport mode: stdio or http
SHELV_MCP_HTTP_HOST127.0.0.1Host to bind in HTTP mode
SHELV_MCP_HTTP_PORT3334Port to bind in HTTP mode
SHELV_MCP_ENABLE_WRITE_TOOLSfalseEnable create_shelf and hydrate_shelf
SHELV_MCP_SEARCH_MAX_FILES500Max files to search across
SHELV_MCP_SEARCH_MAX_BYTES5000000Max total bytes to search
SHELV_MCP_SEARCH_MAX_MATCHES200Max matches to return
SHELV_MCP_READ_MAX_BYTES250000Max bytes for a single file read

​
HTTP transport

Run the server in HTTP mode for shared or remote setups: 
SHELV_MCP_TRANSPORT=http SHELV_MCP_HTTP_PORT=3334 shelv-mcp
In HTTP mode, authenticate each request with an Authorization: Bearer sk_... header unless SHELV_API_KEY is set as a startup fallback.