How do I use Grimmory MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Grimmory MCP Server show me my books" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Grimmory MCP Server

by bannert1337

Overview Schema Related Servers Score Discussions

TypeScript

Remote

Grimmory MCP Server

A Model Context Protocol (MCP) server for the Grimmory book management application. This server enables AI assistants like Claude to interact with your Grimmory library through 53 specialized tools.

GitHub

Features

53 MCP Tools for comprehensive book library management
JWT Authentication with automatic token refresh
Dual Response Formats - JSON for data, Markdown for readability
Stdio Transport - Full MCP compatibility with Claude Desktop and other clients
SSE Support - Streaming endpoints for long-running operations
Type-Safe - Built with TypeScript for reliability

Related MCP server: BookStack MCP Server

Installation

Prerequisites

Bun runtime (recommended) or Node.js 18+
A running Grimmory instance (v2.3.0+)
GitHub CLI (gh) - optional, for repository operations

Setup

# Clone the repository
git clone https://github.com/bannert1337/grimmory-mcp.git
cd grimmory-mcp

# Install dependencies
bun install

# Build the project
bun run build

Configuration

Set the following environment variables:

export GRIMMORY_URL="https://your-grimmory-instance.com"
export GRIMMORY_EMAIL="your-email@example.com"
export GRIMMORY_PASSWORD="your-password"

You can also create a .env file in the project root:

GRIMMORY_URL=https://your-grimmory-instance.com
GRIMMORY_EMAIL=your-email@example.com
GRIMMORY_PASSWORD=your-password

Usage

With Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "grimmory": {
      "command": "bun",
      "args": ["run", "start"],
      "env": {
        "GRIMMORY_URL": "https://your-grimmory-instance.com",
        "GRIMMORY_EMAIL": "your-email@example.com",
        "GRIMMORY_PASSWORD": "your-password"
      }
    }
  }
}

Location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

With Other MCP Clients

The server uses stdio transport, making it compatible with any MCP client:

bun run start

Available Tools (53 Total)

Book Management (2 tools)

Tool	Description
`grimmory_list_books`	List books with pagination, library filtering, and search
`grimmory_get_book`	Get detailed information about a specific book

Library Management (2 tools)

Tool	Description
`grimmory_list_libraries`	List all libraries in the Grimmory instance
`grimmory_get_library`	Get details for a specific library by UUID

Shelf Management (3 tools)

Tool	Description
`grimmory_list_shelves`	List all shelves with optional library filter
`grimmory_get_shelf`	Get details for a specific shelf
`grimmory_get_shelf_books`	Get books in a specific shelf with pagination

Author Management (13 tools)

Tool	Description
`grimmory_list_authors`	List authors with pagination and search
`grimmory_get_author`	Get detailed information about an author
`grimmory_find_author_by_name`	Search for an author by name
`grimmory_get_book_authors`	Get all authors associated with a book
`grimmory_update_author`	Update author name and description
`grimmory_search_author_metadata`	Search external sources for author metadata
`grimmory_match_author`	Link author to a specific metadata provider
`grimmory_quick_match_author`	Automatically find best metadata match
`grimmory_auto_match_authors`	Trigger auto-matching for all unmatched authors
`grimmory_unmatch_authors`	Remove metadata provider associations
`grimmory_search_author_photos`	Search for author photos from providers
`grimmory_set_author_photo_url`	Set author photo via URL
`grimmory_delete_authors`	Delete one or more authors

Reading Progress (3 tools)

Tool	Description
`grimmory_update_read_status`	Update read status (UNREAD, READING, READ, ABANDONED, etc.)
`grimmory_update_rating`	Update personal rating (1-5 stars)
`grimmory_update_progress`	Update reading progress (0-100%)

Notes (3 tools)

Tool	Description
`grimmory_list_notes`	List notes for a book with pagination
`grimmory_create_note`	Create a new note for a book
`grimmory_delete_note`	Delete a note from a book

Reviews (4 tools)

Tool	Description
`grimmory_list_reviews`	List reviews for a specific book
`grimmory_refresh_reviews`	Refresh reviews from external sources
`grimmory_delete_review`	Delete a specific review by ID
`grimmory_delete_all_book_reviews`	Delete all reviews for a book

Metadata Management (13 tools)

Tool	Description
`grimmory_lookup_isbn`	Look up book metadata by ISBN-10 or ISBN-13
`grimmory_batch_isbn_lookup`	Look up multiple ISBNs at once
`grimmory_update_book_metadata`	Update metadata fields for a book
`grimmory_get_file_metadata`	Retrieve file-level metadata
`grimmory_get_comic_info`	Get ComicInfo XML for CBX books
`grimmory_bulk_edit_metadata`	Apply metadata changes to multiple books
`grimmory_toggle_all_locks`	Lock/unlock all metadata fields globally
`grimmory_toggle_field_locks`	Lock/unlock specific metadata fields
`grimmory_get_metadata_lock_fields`	List fields that support locking
`grimmory_recalculate_match_scores`	Recalculate metadata match scores
`grimmory_consolidate_metadata`	Merge metadata from multiple providers
`grimmory_delete_metadata_values`	Delete specific metadata field values
`grimmory_get_prospective_metadata`	Preview potential metadata matches

Sidecar Files (6 tools)

Tool	Description
`grimmory_get_sidecar`	Get sidecar metadata file content
`grimmory_get_sidecar_status`	Check sidecar file sync status
`grimmory_export_sidecar`	Export sidecar for a specific book
`grimmory_import_sidecar`	Import sidecar metadata for a book
`grimmory_bulk_export_sidecar`	Export sidecars for all books in a library
`grimmory_bulk_import_sidecar`	Import sidecars for all books in a library

Statistics & Insights (3 tools)

Tool	Description
`grimmory_get_stats`	Get dashboard statistics (book counts, ratings, status distribution)
`grimmory_get_recommendations`	Get personalized book recommendations
`grimmory_get_notebook`	Get notebook entries (books with notes/highlights)

Example Usage with Claude

Once configured, you can ask Claude to interact with your Grimmory library:

"Show me all books I'm currently reading"
"List my favorite authors"
"Update the rating for 'Dune' to 5 stars"
"Search for books by Isaac Asimov"
"Get statistics about my book collection"
"Create a note for book 123 about the main character"
"List books in my 'Favorites' shelf"

Development

# Development mode with watch
bun run dev

# Run tests
bun test

# Build for production
bun run build

# Type checking
bun run typecheck

# Linting
bun run lint

Project Structure

src/
├── index.ts                    # Entry point
├── constants.ts                # API endpoints and constants
├── types.ts                    # TypeScript type definitions
├── schemas/
│   └── index.ts               # Zod validation schemas
├── services/
│   ├── grimmory-client.ts     # API client with auth
│   └── response-formatter.ts  # Output formatting
└── tools/
    ├── books.ts               # Book management tools
    ├── libraries.ts           # Library management tools
    ├── shelves.ts             # Shelf management tools
    ├── authors.ts             # Author management tools
    ├── reading.ts             # Reading progress tools
    ├── notes.ts               # Notes management tools
    ├── reviews.ts             # Reviews management tools
    ├── metadata.ts            # Metadata management tools
    ├── sidecar.ts             # Sidecar file tools
    └── stats.ts               # Statistics and insights tools

tests/                         # Test suite

API Compatibility

This MCP server is compatible with Grimmory v2.3.0+ and uses the following API endpoints:

/api/v1/auth/* - Authentication
/api/v1/books/* - Book management
/api/v1/libraries/* - Library management
/api/v1/shelves/* - Shelf management
/api/v1/authors/* - Author management
/api/v1/book-notes/* - Notes management
/api/v1/reviews/* - Reviews management
/api/v1/user-stats/* - Statistics
/api/v1/notebook/* - Notebook entries
/api/v1/recommendations/* - Recommendations

Troubleshooting

Authentication Issues

If you see "Authentication failed" errors:

Verify your GRIMMORY_URL, GRIMMORY_EMAIL, and GRIMMORY_PASSWORD are correct
Ensure your Grimmory instance is accessible
Check that the user account has appropriate permissions

Connection Issues

If the server fails to connect:

Verify the Grimmory URL includes the protocol (https://)
Check network connectivity to your Grimmory instance
Ensure no firewall rules are blocking the connection

Empty Responses

Some endpoints return 204 No Content when no data exists (e.g., books without reviews). This is normal behavior.

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Make your changes
Run tests: bun test
Commit with semantic messages: feat:, fix:, refactor:, etc.
Push and create a pull request

License

GPL-3.0 License - See LICENSE for details.

Acknowledgments

Built for Grimmory - A modern book management application
Uses the Model Context Protocol by Anthropic

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/bannert1337/grimmory-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server