{
  "markdown": "# SPINES MCP Server\n\nAccess [SPINES](https://spins.app) book collections, reading lists, and bookshelf data from AI assistants via the [Model Context Protocol](https://modelcontextprotocol.io).\n\n## Features\n\n- Search books by title, author, or ISBN\n- Browse and filter book collections\n- Manage reading lists (add and remove books)\n- Explore personas and categories\n- AI prompts for shelf analysis and book recommendations\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 18+\n- A SPINES API key ([get one here](https://spins.app/settings/developer))\n\n### Installation\n\n```bash\nnpm install -g @spines/mcp-server\n```\n\n### Configuration\n\n#### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"spines\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@spines/mcp-server\"],\n      \"env\": {\n        \"SPINES_API_KEY\": \"gtspn_live_your_key_here\"\n      }\n    }\n  }\n}\n```\n\n#### VS Code / Cursor\n\nAdd to your MCP settings:\n\n```json\n{\n  \"spines\": {\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"@spines/mcp-server\"],\n    \"env\": {\n      \"SPINES_API_KEY\": \"gtspn_live_your_key_here\"\n    }\n  }\n}\n```\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `SPINES_API_KEY` | Yes | - | Your API key |\n| `SPINES_API_URL` | No | `https://spins.app/api/v1` | API base URL |\n| `SPINES_DEBUG` | No | `false` | Verbose logging to stderr |\n\n## Tools\n\n### Read Tools\n\n| Tool | Description |\n|------|-------------|\n| `search_books` | Search for books by title, author, or ISBN |\n| `get_book_details` | Get full details for a specific book |\n| `get_collection` | Get a book collection with all its books |\n| `list_collections` | List your collections with optional filters |\n| `list_categories` | List all approved book categories |\n| `get_persona` | Get details about a persona |\n\n### Write Tools\n\n| Tool | Description |\n|------|-------------|\n| `add_to_reading_list` | Add a book to a reading list |\n| `remove_from_reading_list` | Remove a book from a reading list |\n\n### Tool Details\n\n#### `search_books`\n```\nquery: string    - Search query (title, author, or ISBN)\nlimit?: number   - Max results (1-50, default 10)\n```\n\n#### `get_book_details`\n```\nbook_id: string  - The book's unique ID\n```\n\n#### `get_collection`\n```\ncollection_id: string  - The collection's unique ID\n```\n\n#### `list_collections`\n```\nlimit?: number        - Max results (1-50, default 20)\ncursor?: string       - Pagination cursor\npersona_id?: string   - Filter by persona\ncategory_id?: string  - Filter by category\n```\n\n#### `add_to_reading_list`\n```\nbook_id: string      - The book to add\nlist_name?: string   - List name (default: \"want_to_read\")\n```\n\n#### `remove_from_reading_list`\n```\nentry_id: string     - The reading list entry ID to remove\n```\n\n## Resources\n\n| URI | Description |\n|-----|-------------|\n| `spines://collection/{id}` | A book collection with metadata |\n| `spines://book/{id}` | Full book details |\n| `spines://persona/{id}` | Persona profile and collections |\n| `spines://reading-lists` | User's reading lists |\n\n## Prompts\n\n| Prompt | Description |\n|--------|-------------|\n| `analyze_shelf` | Analyze a collection for themes and reading patterns |\n| `recommend_books` | Get recommendations based on your library |\n| `compare_collections` | Compare two collections for similarities |\n\n## Troubleshooting\n\n| Problem | Solution |\n|---------|----------|\n| \"SPINES_API_KEY is required\" | Set the env var in your MCP client config |\n| 401 errors | Check your API key is valid and not expired |\n| 403 errors | Your key may lack required scopes |\n| 429 errors | Rate limited — wait and retry |\n| Tools not appearing | Restart your MCP client |\n\n## Development\n\n```bash\ngit clone https://github.com/GetSpines/mcp-server\ncd mcp-server\nnpm install\nnpm run build\nnpm test\n```\n\n## License\n\nMIT\n",
  "bytes": 3959,
  "sha": "0e035c276459b64a306575ea178835e873f1b64e2370101aa2786650602efc12",
  "repo_slug": "getspines/mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_superagentic_spines_0df06c1b/readme"
}