zotero-mcp-claude-code: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Zotero MCP is a Zotero plugin that provides Model Context Protocol (MCP) integration, allowing AI clients (Claude Code, Claude Desktop, Cherry Studio, Cursor IDE) to interact with a user's local Zotero library. The plugin includes an integrated MCP server that uses Streamable HTTP protocol.

Architecture: AI Client ↔ Streamable HTTP ↔ Zotero Plugin (integrated MCP server)

Fork: This fork adds Claude Code compatibility. Contributed by lricher7329.

Claude Code Configuration

To use with Claude Code, add this to your MCP configuration (~/.claude.json or .mcp.json):

{
  "mcpServers": {
    "zotero-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:23120/mcp"
    }
  }
}

Build Commands

All commands run from zotero-mcp-plugin/ directory:

npm install          # Install dependencies
npm run build        # Build plugin and run TypeScript type checking
npm run start        # Development mode with auto-reload
npm run lint:check   # Check formatting and linting
npm run lint:fix     # Fix formatting and linting issues
npm run test         # Run tests via zotero-plugin-scaffold

Code Architecture

Entry Points

• src/index.ts - Plugin bootstrap
• src/addon.ts - Main Addon class, exposes API methods
• src/hooks.ts - Lifecycle hooks (startup, shutdown, prefs events), starts HTTP server

Core Modules (src/modules/)

• httpServer.ts - HTTP server using Mozilla nsIServerSocket, routes requests to MCP server or REST endpoints
• streamableMCPServer.ts - MCP protocol implementation, handles JSON-RPC 2.0 requests, defines all MCP tools
• searchEngine.ts - Advanced search with boolean operators, relevance scoring, field queries
• apiHandlers.ts - HTTP request handlers for search, items, collections, fulltext