Spines

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

Tools

Read Tools

Write Tools

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 - Base64-encoded single photo images?: array - Several photos of one bookshelf, saved as ONE collection; each entry is { image_url } or { image_base64 } cover_index?: number - Zero-based index into images of the cover photo (default 0) title?: string - Title for the new collection

Send either image_url / image_base64 or images, not both. Example:

{

"images": [ { "image_url": "https://example.com/shelf-left.jpg" }, { "image_url": "https://example.com/shelf-right.jpg" } ], "cover_index": 1, "title": "Living room" }

• Photo limit: 4 per request with a regular key. A book that appears on two photos is kept once.
• Credits: each photo uses one credit; the request needs at least one to start. With SPINES_LLM_PROVIDER / SPINES_LLM_API_KEY set, no credits are used.
• Prefer URLs. Base64 photos over 4 MB in total do not fit in one request.
• Duplicates: a photo already in SPINES fails the whole request (RECOGNIZE_IMAGE_DUPLICATE, with the index of that photo).
• Timing: the tool waits while the server reads every photo, then polls until book matching finishes (up to 2 minutes). It returns the finished collection, or the job's current status (with its job_id) if matching is still running or its status could not be read. If the first step times out (5 minutes), the collection may still be created: check list_collections before trying again, since a retry uses credits again.

Resources

Prompts

Troubleshooting

Development

git clone https://github.com/GetSpines/mcp-server

cd mcp-server npm install npm run build npm test

License

MIT