Grimmory MCP

Grimmory MCP服务器

](https://github.com/bannert1337/grimmory-mcp)

特性

• 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个工具）

图书馆管理（2个工具）

货架管理（3个工具）

作者管理（13个工具）

阅读进度（3个工具）

注释（3个工具）

评论（4工具）

元数据管理（13个工具）

Sidecar文件（6个工具）

统计与洞察（3个工具）

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/* -建议

故障排除

身份验证问题

如果您看到“身份验证失败”错误：

1. 验证您的 GRIMMORY_URL, GRIMMORY_EMAIL，以及 GRIMMORY_PASSWORD 是正确的
2. 确保您的Grimmory实例可访问
3. 检查用户帐户是否具有适当的权限

连接问题

如果服务器无法连接：

1. 验证Grimmory URL是否包含协议(https://)
2. 检查Grimmory实例的网络连接
3. 确保没有防火墙规则阻止连接

空响应

当不存在数据时（例如，没有评论的书籍），一些端点返回204 No Content。这是正常的行为。

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/my-feature
3. 进行更改
4. 运行测试： bun test
5. 使用语义消息提交： feat:, fix:, refactor:等等。
6. 推送并创建拉取请求

许可证

GPL-3.0许可证-请参阅 许可证 了解详情。

致谢

• 专为 格里莫 -现代图书管理应用程序
• 使用 模型上下文协议 通过Anthropic