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
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 |
| 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 |
| Tool | Description |
|---|
add_to_reading_list | Add a book to a reading list |
remove_from_reading_list | Remove a book from a reading list |
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
