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

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://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

git clone https://github.com/GetSpines/mcp-server
cd mcp-server
npm install
npm run build
npm test

License

MIT

mcp-server