SPINES MCP Server

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

Features

Search books by title, author, or ISBN
Browse and filter book collections
Manage reading lists (add and remove books)
Explore personas and categories
AI prompts for shelf analysis and book recommendations

Quick Start

Prerequisites

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

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

Variable	Required	Default	Description
`SPINES_API_KEY`	Yes	-	Your API key
`SPINES_API_URL`	No	`https://spins.app/api/v1`	API base URL
`SPINES_DEBUG`	No	`false`	Verbose logging to stderr

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

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

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

`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

Resources

URI	Description
`spines://collection/{id}`	A book collection with metadata
`spines://book/{id}`	Full book details
`spines://persona/{id}`	Persona profile and collections
`spines://reading-lists`	User's reading lists

Prompts

Prompt	Description
`analyze_shelf`	Analyze a collection for themes and reading patterns
`recommend_books`	Get recommendations based on your library
`compare_collections`	Compare two collections for similarities

Troubleshooting

Problem	Solution
"SPINES_API_KEY is required"	Set the env var in your MCP client config
401 errors	Check your API key is valid and not expired
403 errors	Your key may lack required scopes
429 errors	Rate limited — wait and retry
Tools not appearing	Restart your MCP client

Development