SPINES MCP Server

Access SPINES book collections, reading lists, and bookshelf data from AI assistants via the Model Context Protocol.

Features

• Recognize books from photos of a bookshelf; several photos of one shelf become one collection
• Search books by title, author, or ISBN
• Browse and filter book collections
• Manage reading lists (add and remove books)
• Explore personas, categories, and books commonly shelved together
• AI prompts for shelf analysis and book recommendations

Quick Start

Prerequisites

• Node.js 18+
• A SPINES API key (get one here)

Installation

npm install -g @spines/mcp-server

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "spines": {
      "command": "npx",
      "args": ["-y", "@spines/mcp-server"],
      "env": {
        "SPINES_API_KEY": "gtspn_live_your_key_here"
      }
    }
  }
}

VS Code / Cursor

Add to your MCP settings:

{
  "spines": {
    "command": "npx",
    "args": ["-y", "@spines/mcp-server"],
    "env": {
      "SPINES_API_KEY": "gtspn_live_your_key_here"
    }
  }
}

Environment Variables

Variable	Required	Default	Description
SPINES_API_KEY	Yes	-	Your API key
SPINES_API_URL	No	https://getspines.com/api/v1	API base URL
SPINES_DEBUG	No	false	Verbose logging to stderr
SPINES_LLM_PROVIDER	No	-	Bring your own LLM key for recognize_bookshelf; only gemini is accepted. Set together with SPINES_LLM_API_KEY
SPINES_LLM_API_KEY	No	-	Your provider API key. With both set, recognition uses your key and no SPINES credits

Tools

Read Tools

Tool	Description
search_books	Search for books by title, author, or ISBN
get_book_details	Get full details for a specific book
get_collection	Get a book collection with all its books
list_collections	List your collections with optional filters
list_categories	List all approved book categories
get_persona	Get details about a persona
get_book_pairings	Find books commonly shelved together with a book (Shelfology)
check_credits	Check your daily recognition credit balance

Write Tools

Tool	Description
add_to_reading_list	Add a book to a reading list
remove_from_reading_list	Remove a book from a reading list
recognize_bookshelf	Recognize books from one or more bookshelf photos and save them as a collection (uses credits)

Tool Details

search_books

query: string    - Search query (title, author, or ISBN)
limit?: number   - Max results (1-50, default 10)

get_book_details

book_id: string  - The book's unique ID

get_collection

collection_id: string  - The collection's unique ID

list_collections

limit?: number        - Max results (1-50, default 20)
cursor?: string       - Pagination cursor
persona_id?: string   - Filter by persona
category_id?: string  - Filter by category

list_categories

(no arguments)

get_persona

persona_id: string  - The persona's unique ID

get_book_pairings

book_id: string  - The book to find pairings for
limit?: number   - Max results (1-50, default 10)

check_credits

(no arguments)

add_to_reading_list

book_id: string      - The book to add
list_name?: string   - List name (default: "want_to_read")

remove_from_reading_list

entry_id: string     - The reading list entry ID to remove

recognize_bookshelf

image_url?: string     - URL of a single photo
image_base64?: string  

... [View full README on GitHub](https://github.com/GetSpines/mcp-server#readme)