# GetSpines Mcp Server

> Access book collections, reading lists, and bookshelf recognition from AI assistants.

- **Type:** MCP server
- **Install:** `agentstack add mcp-getspines-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [GetSpines](https://agentstack.voostack.com/s/getspines)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 1.0.2
- **License:** MIT
- **Upstream author:** [GetSpines](https://github.com/GetSpines)
- **Source:** https://github.com/GetSpines/mcp-server

## Install

```sh
agentstack add mcp-getspines-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# SPINES MCP Server

Access [SPINES](https://spins.app) book collections, reading lists, and bookshelf data from AI assistants via the [Model Context Protocol](https://modelcontextprotocol.io).

## 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](https://spins.app/settings/developer))

### Installation

```bash
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):

```json
{
  "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:

```json
{
  "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

```bash
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](https://github.com/GetSpines)
- **Source:** [GetSpines/mcp-server](https://github.com/GetSpines/mcp-server)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v1.0.2 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **1.0.2** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-getspines-mcp-server
- Seller: https://agentstack.voostack.com/s/getspines
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.