> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shelv.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect any MCP-compatible agent to Shelv with @shelv/mcp — browse, read, and search shelves directly from Claude Code, Cursor, or any MCP client.

`@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](https://github.com/shelv-dev/shelv-mcp)

## Quick setup

Run the server with npx:

```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
npx @shelv/mcp
```

Or install globally:

```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
npm install -g @shelv/mcp
shelv-mcp
```

### Claude Code

```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
claude mcp add shelv -- npx @shelv/mcp
```

Set your API key in the environment where Claude Code runs:

```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
export SHELV_API_KEY="sk_..."
```

<Tip>
  Don't have an API key yet? See the [Authentication
  guide](/guides/authentication#get-an-api-key).
</Tip>

### Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
  "mcpServers": {
    "shelv": {
      "command": "npx",
      "args": ["@shelv/mcp"],
      "env": {
        "SHELV_API_KEY": "sk_..."
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project root:

```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
  "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:

```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
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.