使用说明
Grimmory MCP服务器
A. 模型上下文协议（MCP） 服务器 格里莫 图书管理应用程序。该服务器使像Claude这样的人工智能助手能够通过53个专用工具与您的Grimmory库进行交互。
特性
- 53 MCP工具 图书图书馆综合管理
- JWT身份验证 具有自动令牌刷新功能
- 双响应格式 -JSON用于数据，Markdown用于可读性
- 标准输入输出传输 -与Claude Desktop和其他客户端完全兼容MCP
- SSE支持 -长时间运行操作的流式端点
- 类型安全 -使用TypeScript构建以提高可靠性
安装
先决条件
- 包子 运行时（推荐）或Node.js 18+
- 正在运行的Grimmory实例（v2.3.0+）
- GitHub命令行界面(
gh)-可选，用于存储库操作
设置
# 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
配置
设置以下环境变量：
export GRIMMORY_URL="https://your-grimmory-instance.com"
export GRIMMORY_EMAIL="your-email@example.com"
export GRIMMORY_PASSWORD="your-password"
您还可以创建 .env 项目根目录中的文件：
GRIMMORY_URL=https://your-grimmory-instance.com
GRIMMORY_EMAIL=your-email@example.com
GRIMMORY_PASSWORD=your-password
用法
使用克劳德桌面
将以下内容添加到您的 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"
}
}
}
}
地点：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户：
%APPDATA%/Claude/claude_desktop_config.json
与其他MCP客户端
服务器使用stdio传输，使其与任何MCP客户端兼容：
bun run start
可用工具（共53个）
图书管理（2个工具）
| 工具 | 说明 |
|---|---|
grimmory_list_books |
列出具有分页、库过滤和搜索功能的书籍 |
grimmory_get_book |
获取特定书籍的详细信息 |
图书馆管理（2个工具）
| 工具 | 说明 |
|---|---|
grimmory_list_libraries |
列出Grimmory实例中的所有库 |
grimmory_get_library |
通过UUID获取特定库的详细信息 |
货架管理（3个工具）
| 工具 | 说明 |
|---|---|
grimmory_list_shelves |
列出所有带有可选库过滤器的书架 |
grimmory_get_shelf |
获取特定货架的详细信息 |
grimmory_get_shelf_books |
将书籍放在带有分页的特定书架上 |
作者管理（13个工具）
| 工具 | 说明 |
|---|---|
grimmory_list_authors |
使用分页和搜索功能列出作者 |
grimmory_get_author |
获取作者的详细信息 |
grimmory_find_author_by_name |
按姓名搜索作者 |
grimmory_get_book_authors |
获取与一本书相关的所有作者 |
grimmory_update_author |
更新作者姓名和描述 |
grimmory_search_author_metadata |
在外部源中搜索作者元数据 |
grimmory_match_author |
将作者链接到特定的元数据提供者 |
grimmory_quick_match_author |
自动查找最佳元数据匹配 |
grimmory_auto_match_authors |
触发所有未匹配作者的自动匹配 |
grimmory_unmatch_authors |
删除元数据提供程序关联 |
grimmory_search_author_photos |
从提供商处搜索作者照片 |
grimmory_set_author_photo_url |
通过URL设置作者照片 |
grimmory_delete_authors |
删除一个或多个作者 |
阅读进度（3个工具）
| 工具 | 说明 |
|---|---|
grimmory_update_read_status |
更新读取状态（UNREAD、READING、read、ABANDONED等） |
grimmory_update_rating |
更新个人评分（1-5星） |
grimmory_update_progress |
更新阅读进度（0-100%） |
注释（3个工具）
| 工具 | 说明 |
|---|---|
grimmory_list_notes |
列出带页码的书籍注释 |
grimmory_create_note |
为书籍创建新笔记 |
grimmory_delete_note |
从书中删除笔记 |
评论（4工具）
| 工具 | 说明 |
|---|---|
grimmory_list_reviews |
列出特定书籍的评论 |
grimmory_refresh_reviews |
刷新外部来源的评论 |
grimmory_delete_review |
按ID删除特定评论 |
grimmory_delete_all_book_reviews |
删除一本书的所有评论 |
元数据管理（13个工具）
| 工具 | 说明 |
|---|---|
grimmory_lookup_isbn |
按ISBN-10或ISBN-13查找图书元数据 |
grimmory_batch_isbn_lookup |
一次查找多个ISBN |
grimmory_update_book_metadata |
更新书籍的元数据字段 |
grimmory_get_file_metadata |
检索文件级元数据 |
grimmory_get_comic_info |
获取CBX书籍的ComicInfo XML |
grimmory_bulk_edit_metadata |
将元数据更改应用于多本书 |
grimmory_toggle_all_locks |
全局锁定/解锁所有元数据字段 |
grimmory_toggle_field_locks |
锁定/解锁特定元数据字段 |
grimmory_get_metadata_lock_fields |
列出支持锁定的字段 |
grimmory_recalculate_match_scores |
重新计算元数据匹配分数 |
grimmory_consolidate_metadata |
合并来自多个提供程序的元数据 |
grimmory_delete_metadata_values |
删除特定元数据字段值 |
grimmory_get_prospective_metadata |
预览潜在的元数据匹配 |
Sidecar文件（6个工具）
| 工具 | 说明 |
|---|---|
grimmory_get_sidecar |
获取sidecar元数据文件内容 |
grimmory_get_sidecar_status |
检查sidecar文件同步状态 |
grimmory_export_sidecar |
导出特定书籍的sidecar |
grimmory_import_sidecar |
为书籍导入sidecar元数据 |
grimmory_bulk_export_sidecar |
为图书馆中的所有书籍导出侧车 |
grimmory_bulk_import_sidecar |
为图书馆中的所有书籍导入侧车 |
统计与洞察（3个工具）
| 工具 | 说明 |
|---|---|
grimmory_get_stats |
获取仪表板统计数据（图书计数、评级、状态分布） |
grimmory_get_recommendations |
获取个性化书籍推荐 |
grimmory_get_notebook |
获取笔记本条目（带笔记/亮点的书籍） |
Claude使用示例
配置后，您可以让Claude与您的Grimmory库进行交互：
"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 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
项目结构
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兼容性
此MCP服务器与 Grimmory v2.3.0+ 并使用以下API端点：
/api/v1/auth/*-身份验证/api/v1/books/*-图书管理/api/v1/libraries/*-图书馆管理/api/v1/shelves/*-货架管理/api/v1/authors/*-作者管理/api/v1/book-notes/*-笔记管理/api/v1/reviews/*-评审管理/api/v1/user-stats/*-统计数据/api/v1/notebook/*-笔记本条目/api/v1/recommendations/*-建议
故障排除
身份验证问题
如果您看到“身份验证失败”错误：
- 验证您的
GRIMMORY_URL,GRIMMORY_EMAIL，以及GRIMMORY_PASSWORD是正确的 - 确保您的Grimmory实例可访问
- 检查用户帐户是否具有适当的权限
连接问题
如果服务器无法连接：
- 验证Grimmory URL是否包含协议(
https://) - 检查Grimmory实例的网络连接
- 确保没有防火墙规则阻止连接
空响应
当不存在数据时（例如，没有评论的书籍），一些端点返回204 No Content。这是正常的行为。
贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支：
git checkout -b feature/my-feature - 进行更改
- 运行测试：
bun test - 使用语义消息提交：
feat:,fix:,refactor:等等。 - 推送并创建拉取请求
许可证
GPL-3.0许可证-请参阅 许可证 了解详情。
