Lets an AI assistant manage book collections, search for books, and recognize bookshelves from photos.
Also known as GetSpines/mcp-server, mcp-server, @spines/mcp-server
- Stars
- 0
- Tools
- 11
- Downloads, 30 days
- —
- Latest version
- 1.1.0
- Last commit
- Oct 14, 2026
- License
- MIT
What is Spines MCP?
Spines lets an AI assistant manage book collections, search for books, and recognize bookshelves from photos. It exposes 11 tools, such as search_books, get_book_details, get_collection.
Summary generated from the project's README
About Spines MCP server
Spines allows AI assistants to interact with personal book collections, reading lists, and library data. Users can manage their reading habits by searching for books via title, author, or ISBN, or by browsing through specific categories and personas. The server works with local clients like Claude Desktop or VS Code and Cursor through the Model Context Protocol.
One unique capability is the ability to digitize physical libraries using the recognize_bookshelf tool. This tool processes one or more photos of a bookshelf to create a new collection. While this process typically uses credits, users can provide their own Gemini API key via the SPINES_LLM_PROVIDER and SPINES_LLM_API_KEY environment variables to avoid using SPINES credits.
Developers can use specific tools to find book pairings through Shelfology, check their daily recognition credit balance, or add and remove items from reading lists. The server also provides specialized prompts for analyzing shelf themes, comparing different collections, or generating book recommendations based on existing library data.
What you can do with it
- 1Digitize a physical bookshelfConvert photos of your library into a digital collection automatically.
- 2Find related reading materialIdentify books that are frequently shelved alongside a specific title.
- 3Manage reading listsUpdate your want-to-read list by adding or removing specific books.
- 4Analyze library patternsUse AI to discover themes and reading habits within your collections.
Written from the project's README. Every use case is checked against a quote from it.
How to install Spines MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Spines MCP in Claude Code
$ claude mcp add --env 'SPINES_API_KEY=<YOUR_SPINES_API_KEY>' mcp-server -- npx -y @spines/mcp-serverInstall Spines MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@spines/mcp-server"
],
"env": {
"SPINES_API_KEY": "<YOUR_SPINES_API_KEY>"
}
}
}
}Install Spines MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@spines/mcp-server"
],
"env": {
"SPINES_API_KEY": "<YOUR_SPINES_API_KEY>"
}
}
}
}Install Spines MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-server","type":"stdio","command":"npx","args":["-y","@spines/mcp-server"],"env":{"SPINES_API_KEY":"<YOUR_SPINES_API_KEY>"}}'Install Spines MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@spines/mcp-server"
],
"env": {
"SPINES_API_KEY": "<YOUR_SPINES_API_KEY>"
}
}
}
}Install Spines MCP in Codex
$ codex mcp add mcp-server --env 'SPINES_API_KEY=<YOUR_SPINES_API_KEY>' -- npx -y @spines/mcp-serverInstall Spines MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-server] command = "npx" args = ["-y", "@spines/mcp-server"] [mcp_servers.mcp-server.env] SPINES_API_KEY = "<YOUR_SPINES_API_KEY>"
Install Spines MCP in Gemini CLI
$ gemini mcp add -s user -e 'SPINES_API_KEY=<YOUR_SPINES_API_KEY>' mcp-server npx -- -y @spines/mcp-serverInstall Spines MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@spines/mcp-server"
],
"env": {
"SPINES_API_KEY": "<YOUR_SPINES_API_KEY>"
}
}
}
}Spines MCP tools 11
Detected from the READMEsearch_booksget_book_detailsget_collectionlist_collectionslist_categoriesget_personaget_book_pairingscheck_creditsadd_to_reading_listremove_from_reading_listrecognize_bookshelf
| search_books | — | |
| get_book_details | — | |
| get_collection | — | |
| list_collections | — | |
| list_categories | — | |
| get_persona | — | |
| get_book_pairings | — | |
| check_credits | — | |
| add_to_reading_list | — | |
| remove_from_reading_list | — | |
| recognize_bookshelf | — |
Configuration
SPINES_API_KEYRequiredSecretYour SPINES API key
| Name | Description | |
|---|---|---|
| SPINES_API_KEY | Your SPINES API key | RequiredSecret |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubSPINES 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
- 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://getspines.com/api/v1 |
API base URL |
SPINES_DEBUG |
No | false |
Verbose logging to stderr |
SPINES_LLM_PROVIDER |
No | - | Bring your own LLM key for recognize_bookshelf; only gemini is accepted. Set together with SPINES_LLM_API_KEY |
SPINES_LLM_API_KEY |
No | - | Your provider API key. With both set, recognition uses your key and no SPINES credits |
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 |
get_book_pairings |
Find books commonly shelved together with a book (Shelfology) |
check_credits |
Check your daily recognition credit balance |
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 |
recognize_bookshelf |
Recognize 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 cursor
persona_id?: string - Filter by persona
category_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 for
limit?: number - Max results (1-50, default 10)
check_credits
(no arguments)
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
recognize_bookshelf
image_url?: string - URL of a single photo
image_base64?: string - Base64-encoded single photo
images?: 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:
{
"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_KEYset, 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: checklist_collectionsbefore trying again, since a retry uses credits again.
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 |
TIMEOUT from recognize_bookshelf |
The server may still be working; check list_collections before resending |
| 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
Spines MCP questions
How do I add Spines MCP to Claude Code?
Run claude mcp add --env 'SPINES_API_KEY=<YOUR_SPINES_API_KEY>' mcp-server -- npx -y @spines/mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add Spines MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Spines MCP provide?
It exposes 11 tools, including search_books, get_book_details, get_collection, list_collections, list_categories.
How can I recognize books from my bookshelf?
You can use the recognize_bookshelf tool to process one or more photos of a bookshelf and save them as a collection.
Can I use my own LLM for bookshelf recognition to save credits?
Yes, if you set SPINES_LLM_PROVIDER to 'gemini' and provide a SPINES_LLM_API_KEY, recognition uses your key and no SPINES credits.
How many photos can I upload at once for recognition?
You can upload up to 4 photos per request when using a regular key.