MCP Server

@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

Tool	Description	Mode
`list_shelves`	List shelves available to the authenticated user	Read
`get_shelf_tree`	Get the full file tree and file contents for a shelf	Read
`read_shelf_file`	Read a single file from a shelf	Read
`search_shelf`	Search for text across files in a shelf	Read
`create_shelf`	Upload a local PDF and create a shelf	Write
`hydrate_shelf`	Download and write shelf files into a local directory	Write

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

Variable	Default	Description
`SHELV_API_KEY`	—	API key for authentication (required)
`SHELV_MCP_TRANSPORT`	`stdio`	Transport mode: `stdio` or `http`
`SHELV_MCP_HTTP_HOST`	`127.0.0.1`	Host to bind in HTTP mode
`SHELV_MCP_HTTP_PORT`	`3334`	Port to bind in HTTP mode
`SHELV_MCP_ENABLE_WRITE_TOOLS`	`false`	Enable `create_shelf` and `hydrate_shelf`
`SHELV_MCP_SEARCH_MAX_FILES`	`500`	Max files to search across
`SHELV_MCP_SEARCH_MAX_BYTES`	`5000000`	Max total bytes to search
`SHELV_MCP_SEARCH_MAX_MATCHES`	`200`	Max matches to return
`SHELV_MCP_READ_MAX_BYTES`	`250000`	Max 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.

Getting Started

Concepts

Agent Integrations

Guides

Quick setup

Claude Code

Claude Desktop

Cursor

Available tools

Write tools

Environment variables

HTTP transport

​Quick setup

​Claude Code

​Claude Desktop

​Cursor

​Available tools

​Write tools

​Environment variables

​HTTP transport

Quick setup

Claude Code

Claude Desktop

Cursor

Available tools

Write tools

Environment variables

HTTP transport