### Start MCP Inspector for Local Development

Source: https://github.com/kujenga/zotero-mcp/blob/main/README.md

Use this command to start the MCP Inspector for local development with the zotero-mcp project. Ensure you have installed dependencies with `uv sync`.

```bash
npx @modelcontextprotocol/inspector uv run zotero-mcp
```

--------------------------------

### Run Zotero MCP Server from Command Line

Source: https://context7.com/kujenga/zotero-mcp/llms.txt

Starts the Zotero MCP server with different transport options. Use stdio for client integration or SSE for web clients. Can also be run using uvx or uv.

```bash
zotero-mcp
```

```bash
zotero-mcp --transport sse
```

```bash
uvx zotero-mcp
```

```bash
uv run zotero-mcp
```

--------------------------------

### Start MCP Inspector with Zotero Server

Source: https://context7.com/kujenga/zotero-mcp/llms.txt

Launches the MCP Inspector to test and debug the Zotero MCP server. Supports local execution with environment variables or Docker.

```bash
npx @modelcontextprotocol/inspector uv run zotero-mcp
```

```bash
npx @modelcontextprotocol/inspector \
    -e ZOTERO_API_KEY=$ZOTERO_API_KEY \
    -e ZOTERO_LIBRARY_ID=$ZOTERO_LIBRARY_ID \
    docker run --rm -i \
        --env ZOTERO_API_KEY \
        --env ZOTERO_LIBRARY_ID \
        zotero-mcp:local
```

--------------------------------

### Run Test Suite

Source: https://github.com/kujenga/zotero-mcp/blob/main/README.md

Execute the project's test suite using `pytest`. Ensure you have installed the necessary development dependencies.

```bash
uv run pytest
```

--------------------------------

### Get Attachment Details and Full Text

Source: https://context7.com/kujenga/zotero-mcp/llms.txt

Retrieves the best available attachment for a Zotero item, prioritizing PDF, then HTML. It then fetches the full text content using the attachment's key.

```python
from zotero_mcp.client import get_zotero_client, get_attachment_details

zot = get_zotero_client()
item = zot.item("ABCD1234")

# Get best available attachment (prioritizes PDF > HTML > others)
attachment = get_attachment_details(zot, item)

if attachment:
    print(f"Attachment Key: {attachment.key}")
    print(f"Content Type: {attachment.content_type}")
    # Output:
    # Attachment Key: XYZ789
    # Content Type: application/pdf

    # Retrieve full text using attachment key
    fulltext_data = zot.fulltext_item(attachment.key)
    if fulltext_data and "content" in fulltext_data:
        print(fulltext_data["content"])
else:
    print("No suitable attachment found")
```

--------------------------------

### Configure uvx with Local Zotero API

Source: https://github.com/kujenga/zotero-mcp/blob/main/README.md

Configuration for using the zotero-mcp server with Claude Desktop via `uvx` and the local Zotero API. Ensure Zotero desktop application has the local API enabled.

```json
{
  "mcpServers": {
    "zotero": {
      "command": "uvx",
      "args": ["--upgrade", "zotero-mcp"],
      "env": {
        "ZOTERO_LOCAL": "true",
        "ZOTERO_API_KEY": "",
        "ZOTERO_LIBRARY_ID": ""
      }
    }
  }
}
```

--------------------------------

### Build Docker Container Image

Source: https://github.com/kujenga/zotero-mcp/blob/main/README.md

Build the Docker container image for local development and testing. This command tags the image as `zotero-mcp:local`.

```bash
docker build . -t zotero-mcp:local
```

--------------------------------

### Configure Zotero Local API Environment Variables

Source: https://context7.com/kujenga/zotero-mcp/llms.txt

Set these environment variables to connect Zotero MCP to the local Zotero desktop application API. Ensure the Zotero desktop app is running.

```bash
export ZOTERO_LOCAL=true
export ZOTERO_API_KEY=""
export ZOTERO_LIBRARY_ID=""
```

--------------------------------

### Configure Claude Desktop for Local zotero-mcp

Source: https://github.com/kujenga/zotero-mcp/blob/main/README.md

Configure Claude Desktop to use your local zotero-mcp development instance. Set the `command` to the absolute path of the zotero-mcp executable within your project's virtual environment.

```json
{
  "mcpServers": {
    "zotero": {
      "command": "/path/to/zotero-mcp/.venv/bin/zotero-mcp"
      "env": {
        // Whatever configuration is desired.
      }
    }
  }
}
```

--------------------------------

### Initialize Zotero Client and Perform Operations

Source: https://context7.com/kujenga/zotero-mcp/llms.txt

Initializes the Zotero client, which automatically configures authentication via environment variables. The client can then be used for standard pyzotero operations.

```python
from zotero_mcp.client import get_zotero_client

# Client is configured via environment variables
# For local API: ZOTERO_LOCAL=true
# For web API: ZOTERO_API_KEY and ZOTERO_LIBRARY_ID required

zot = get_zotero_client()

# The client can then be used for direct pyzotero operations
items = zot.items()
item = zot.item("ITEMKEY")
children = zot.children("ITEMKEY")
fulltext = zot.fulltext_item("ATTACHMENTKEY")
```

--------------------------------

### Configure Zotero Web API Environment Variables

Source: https://context7.com/kujenga/zotero-mcp/llms.txt

Set these environment variables to connect Zotero MCP to the Zotero Web API. Replace placeholders with your actual API key and library ID.

```bash
export ZOTERO_LOCAL=false
export ZOTERO_API_KEY="your_api_key_here"
export ZOTERO_LIBRARY_ID="your_user_id"
export ZOTERO_LIBRARY_TYPE="user"
```

--------------------------------

### Test Docker Container with MCP Inspector

Source: https://github.com/kujenga/zotero-mcp/blob/main/README.md

Run the zotero-mcp Docker container and test it with the MCP inspector. This command forwards necessary environment variables and maps the container's ports.

```bash
npx @modelcontextprotocol/inspector \
    -e ZOTERO_API_KEY=$ZOTERO_API_KEY \
    -e ZOTERO_LIBRARY_ID=$ZOTERO_LIBRARY_ID \
    docker run --rm -i \
        --env ZOTERO_API_KEY \
        --env ZOTERO_LIBRARY_ID \
        zotero-mcp:local
```

--------------------------------

### Configure Docker with Zotero Web API

Source: https://github.com/kujenga/zotero-mcp/blob/main/README.md

Configuration for running the zotero-mcp server in a Docker container using the Zotero Web API. Replace placeholders with your actual API key and library ID. For local API access, network connectivity to the Zotero application must be configured.

```json
{
  "mcpServers": {
    "zotero": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "ZOTERO_API_KEY=PLACEHOLDER",
        "-e", "ZOTERO_LIBRARY_ID=PLACEHOLDER",
        "ghcr.io/kujenga/zotero-mcp:main"
      ],
    }
  }
}
```

--------------------------------

### Docker Configuration for Zotero Web API

Source: https://context7.com/kujenga/zotero-mcp/llms.txt

Run Zotero MCP in a Docker container for isolated deployment using the Zotero Web API. This configuration includes necessary environment variables for authentication and library identification.

```json
{
  "mcpServers": {
    "zotero": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "ZOTERO_API_KEY=your_api_key_here",
        "-e", "ZOTERO_LIBRARY_ID=your_library_id",
        "ghcr.io/kujenga/zotero-mcp:main"
      ]
    }
  }
}
```

--------------------------------

### Search Zotero Items by Query

Source: https://context7.com/kujenga/zotero-mcp/llms.txt

Use the `search_items` function to find items in your Zotero library. Supports basic searches, full-text searches, and filtering by tags. Results include item keys for further retrieval.

```python
from zotero_mcp import search_items

# Basic search by title, creator, or year
result = search_items("machine learning")

# Search everything (including full text) with custom limit
result = search_items(
    query="neural networks",
    qmode="everything",
    limit=5
)

# Search with tag filtering (supports boolean)
result = search_items(
    query="attention mechanism",
    qmode="titleCreatorYear",
    tag="machine-learning",
    limit=10
)

# Search for notes
result = search_items("research notes", qmode="everything")
```

--------------------------------

### Retrieve Full Text from Zotero Item

Source: https://context7.com/kujenga/zotero-mcp/llms.txt

Fetches the full text content from a Zotero item, handling cases with and without attachments, or attachments with unextractable text.

```python
result = get_item_fulltext("ABCD1234")
```

```python
result = get_item_fulltext("NOATTACH")
```

```python
result = get_item_fulltext("SCANNED123")
```

--------------------------------

### Retrieve Zotero Item Metadata

Source: https://context7.com/kujenga/zotero-mcp/llms.txt

Use `get_item_metadata` to fetch detailed bibliographic information for a specific Zotero item using its item key. Handles both regular items and notes, returning formatted metadata or an error message if the item is not found.

```python
from zotero_mcp import get_item_metadata

# Retrieve full metadata for an item
result = get_item_metadata("ABCD1234")

# Handle non-existent items
result = get_item_metadata("NONEXISTENT")

# Retrieve note metadata
result = get_item_metadata("NOTE789")
```

--------------------------------

### Extract Full Text from Zotero Item

Source: https://context7.com/kujenga/zotero-mcp/llms.txt

The `get_item_fulltext` function retrieves the full text content from a Zotero item, prioritizing PDF attachments and then other formats like HTML. This tool is essential for accessing the content of research papers.

```python
from zotero_mcp import get_item_fulltext

# Example usage (actual code not provided in source, only import)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.