scan-mcp MCP Server Setup

Configure the scan-mcp MCP server in Claude Code's global configuration to enable scanner control.

Setup Workflow

Step 1: Gather User Preferences

Ask user for:

1. •INBOX_DIR location (default: ~/Documents/scanned_documents/inbox)
2. •Installation method: npx (recommended) or local

Step 2: Run Preflight Checks

npx -y scan-mcp --preflight-only

Expected on success: All checks passed!

If preflight fails: Parse output to identify missing dependencies, then guide user through installation (see PLATFORMS.md).

Common missing items:

• •SANE utilities (scanimage, scanadf)
• •TIFF tools (tiffcp or ImageMagick convert)

Step 3: Locate Claude Code MCP Configuration

Claude Code config location:

• •~/.config/claude/config.json (Linux/macOS)
• •Create if doesn't exist

Step 4: Add or Update Configuration

Configuration structure (npx - recommended):

{
  "mcpServers": {
    "scan": {
      "command": "npx",
      "args": ["-y", "scan-mcp"],
      "env": {
        "INBOX_DIR": "~/Documents/scanned_documents/inbox"
      }
    }
  }
}

Important:

• •If config.json doesn't exist: Create it with scan-mcp server entry
• •If config.json exists but no mcpServers: Add mcpServers section
• •If mcpServers exists: Add or update "scan" entry
• •Preserve existing MCP server configurations

For local installation (advanced): See ADVANCED.md.

Step 5: Verify Configuration

1. •Inform user that Claude Code needs restart to pick up new configuration
2. •Suggest testing: claude mcp or asking "scan this document"
3. •If issues occur, suggest running /doctor

Quick Example

User: "Setup scan-mcp"

Actions:

1. •Ask: "Where would you like scanned documents stored? (Default: ~/Documents/scanned_documents/inbox)"
2. •Run: npx -y scan-mcp --preflight-only
3. •If preflight passes:
   • •Locate/create ~/.config/claude/config.json
   • •Add scan-mcp server configuration
   • •Confirm: "scan-mcp configured. Please restart Claude Code. Test with 'scan this document'."
4. •If preflight fails:
   • •Identify missing dependencies
   • •Provide installation commands (see PLATFORMS.md)
   • •Re-run preflight after user installs

Reference Materials

• •PLATFORMS.md — Platform-specific prerequisite installation
• •SCANNERS.md — Scanner permissions and device setup
• •TROUBLESHOOTING.md — Common setup issues and solutions
• •ADVANCED.md — Local installation, multiple configs, advanced options