Installation Guide

Detailed instructions to get Zotero MCP up and running.

Prerequisites Smithery Installation Pip Installation Configuration Verification

Prerequisites

Before installing Zotero MCP, make sure you have the following prerequisites:

Required Software

  • Python 3.10+ - The tool is built on Python and requires version 3.10 or newer.
  • Zotero 7+ - For local API with full-text access.
  • Claude Desktop - Or another compatible MCP-enabled AI assistant.

For Local API Use (Recommended)

To use the local Zotero API:

  1. Open Zotero
  2. Go to Edit > Preferences > Advanced > API
  3. Check "Enable local API"
  4. Click OK to save the settings
Using the local API is recommended for the best experience, as it provides full-text access to your library.

For Web API Use

If you plan to use the Zotero Web API, you'll need:

  1. Zotero API Key - Create one at https://www.zotero.org/settings/keys
  2. Library ID - Your user ID or group ID
Note that the Web API doesn't provide direct access to attachments, so full-text extraction may not be available.

Smithery Installation

Smithery is a package manager for AI assistants that makes installing tools like Zotero MCP quick and easy:

Installation Steps

  1. Make sure you have Node.js installed on your system (required for the npx command).
  2. Open a terminal or command prompt.
  3. Run the following command:
npx -y @smithery/cli install @54yyyu/zotero-mcp --client claude

This command will:

  • Install the latest version of Zotero MCP
  • Configure it for use with Claude Desktop
  • Set up everything automatically
If the installation completes successfully, you should see a confirmation message. Smithery will handle all the configuration details for you.

Pip Installation

Follow these steps to install Zotero MCP using pip:

Installation Steps

  1. Open a terminal or command prompt.
  2. Run the following command to install from GitHub:
pip install git+https://github.com/54yyyu/zotero-mcp.git

Or install a specific version if needed:

pip install git+https://github.com/54yyyu/zotero-mcp.git@v0.1.0

Auto-Configuration for Claude Desktop

After installation, run the auto-configuration tool to set up Zotero MCP with Claude Desktop:

zotero-mcp setup

The setup tool will:

  • Find the installed Zotero MCP executable
  • Locate your Claude Desktop configuration file
  • Update the configuration to include Zotero MCP
  • Set up local API access by default
You'll need to restart Claude Desktop after running the setup command for the changes to take effect.

Configuration Options

Local API Configuration

To configure for local API use (default):

zotero-mcp setup

This will add the following to your Claude Desktop config:

{
  "mcpServers": {
    "zotero": {
      "command": "zotero-mcp",
      "env": {
        "ZOTERO_LOCAL": "true"
      }
    }
  }
}

Web API Configuration

To configure for Web API use:

zotero-mcp setup --no-local --api-key YOUR_API_KEY --library-id YOUR_LIBRARY_ID

Replace YOUR_API_KEY and YOUR_LIBRARY_ID with your actual Zotero API key and library ID.

Manual Configuration File Editing

You can also edit your Claude Desktop configuration file manually. The file is located at:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Add the Zotero MCP configuration to the mcpServers section of the file.

Environment Variables

Instead of using the configuration file, you can also set environment variables:

# For local API
export ZOTERO_LOCAL=true

# For web API
export ZOTERO_API_KEY=your_api_key
export ZOTERO_LIBRARY_ID=your_library_id
export ZOTERO_LIBRARY_TYPE=user  # or 'group' for group libraries

Verification

To verify that Zotero MCP is installed and configured correctly:

Check Installation

  1. Open a terminal or command prompt.
  2. Run the following command to check the version:
zotero-mcp version

You should see output showing the installed version of Zotero MCP.

Test with Claude Desktop

  1. Make sure Zotero is running and the local API is enabled.
  2. Launch Claude Desktop.
  3. In a conversation with Claude, type: /tools zotero to activate the Zotero tool.
  4. Try a simple query like: "List my recent additions to Zotero"

If everything is set up correctly, Claude should be able to access your Zotero library and display results.

If you encounter any issues, check the Troubleshooting section or submit an issue on GitHub.