GetSpines Mcp Server

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 | |---------|----------| | "SPINESAPIKEY 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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: GetSpines
• Source: GetSpines/mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.