Spines

io.github.SuperAgenticPublished by GitHub account SuperAgenticv1.1.0Updated Oct 24, 2026

Access book collections, reading lists, and bookshelf recognition from AI assistants.

VerifiedSTDIODesktop onlyKnowledge & MemoryMedia & Design

Overview

AI-generated overview

Connects an AI assistant to SPINES book collections, letting it search books, browse shelves, manage reading lists and recognize books from bookshelf photos.

What you can do
  • Search books by title, author or ISBN and read full book details
  • Browse collections, categories and personas, and find books commonly shelved together
  • Add books to or remove books from reading lists
  • Recognize books from one or more bookshelf photos and save them as a collection
  • Check the daily recognition credit balance
  • Expose collections, books, personas and reading lists as resources, plus prompts for shelf analysis, recommendations and collection comparison
When to use it
Useful when you keep a SPINES library and want an assistant to look up books, curate reading lists, or turn photos of a physical bookshelf into a digital collection with analysis and recommendations.
Requirements
Runs locally via npm package @spines/mcp-server on Node.js 18 or later, configured in an MCP client such as Claude Desktop, VS Code or Cursor. Requires a SPINES API key in the SPINES_API_KEY environment variable. Optional settings: SPINES_API_URL, SPINES_DEBUG, and SPINES_LLM_PROVIDER with SPINES_LLM_API_KEY. Network access to the SPINES API.
Before you install
The API key is a live credential stored in the client config; keep it private. recognize_bookshelf spends one credit per photo and retries after a timeout can spend credits again, so check collections first. It also writes data: it creates collections and changes reading lists. Photos sent by URL or base64 go to SPINES, and a duplicate photo fails the whole request.

Installation

In SourceWeft

  1. Open Spines in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

Installation

bash
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):

json
{  "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:

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

Environment Variables

VariableRequiredDefaultDescription
SPINES_API_KEYYes-Your API key
SPINES_API_URLNohttps://getspines.com/api/v1API base URL
SPINES_DEBUGNofalseVerbose logging to stderr
SPINES_LLM_PROVIDERNo-Bring your own LLM key for recognize_bookshelf; only gemini is accepted. Set together with SPINES_LLM_API_KEY
SPINES_LLM_API_KEYNo-Your provider API key. With both set, recognition uses your key and no SPINES credits

Tools

Read Tools

ToolDescription
search_booksSearch for books by title, author, or ISBN
get_book_detailsGet full details for a specific book
get_collectionGet a book collection with all its books
list_collectionsList your collections with optional filters
list_categoriesList all approved book categories
get_personaGet details about a persona
get_book_pairingsFind books commonly shelved together with a book (Shelfology)
check_creditsCheck your daily recognition credit balance

Write Tools

ToolDescription
add_to_reading_listAdd a book to a reading list
remove_from_reading_listRemove a book from a reading list
recognize_bookshelfRecognize 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 cursorpersona_id?: string   - Filter by personacategory_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 forlimit?: number   - Max results (1-50, default 10)
check_credits
(no arguments)
add_to_reading_list
book_id: string      - The book to addlist_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 photoimage_base64?: string  - Base64-encoded single photoimages?: 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:

json
{  "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

URIDescription
spines://collection/{id}A book collection with metadata
spines://book/{id}Full book details
spines://persona/{id}Persona profile and collections
spines://reading-listsUser's reading lists

Prompts

PromptDescription
analyze_shelfAnalyze a collection for themes and reading patterns
recommend_booksGet recommendations based on your library
compare_collectionsCompare two collections for similarities

Troubleshooting

ProblemSolution
"SPINES_API_KEY is required"Set the env var in your MCP client config
401 errorsCheck your API key is valid and not expired
403 errorsYour key may lack required scopes
429 errorsRate limited — wait and retry
TIMEOUT from recognize_bookshelfThe server may still be working; check list_collections before resending
Tools not appearingRestart your MCP client

Development

bash
git clone https://github.com/GetSpines/mcp-servercd mcp-servernpm installnpm run buildnpm test

License

MIT

Source: README.md at commit 64fb770

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

3
  1. v1.1.0LatestOct 14, 2026
  2. v1.0.3Oct 14, 2026
  3. v1.0.2Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts