io.github.SuperAgentic/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