Koha MCP Server
# Koha MCP Server
An MCP server for searching the GBS Flexon Library catalog (Koha) and checking book availability.
## Setup
1. Clone and install:
```bash
git clone https://github.com/wrecks1997/koha-mcp-server.git
cd koha-mcp-server
npm install
npm run build
```
2. Copy `.env.example` to `.env` and fill in credentials:
```bash
cp .env.example .env
```
3. Add to Claude Code settings (`~/.claude/settings.json`):
```json
{
"mcpServers": {
"koha-library": {
"command": "node",
"args": ["/path/to/koha-mcp-server/dist/index.js"],
"env": {
"KOHA_BASE_URL": "https://staff.gbsc.bywatersolutions.com",
"KOHA_USERNAME": "your-username",
"KOHA_PASSWORD": "your-password"
}
}
}
}
```
## Tools
### search_books
Search the catalog by title, author, ISBN, subject, or keyword.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| query | string | yes | — | Search term |
| search_type | enum | no | keyword | title, author, isbn, subject, keyword |
| limit | number | no | 10 | Max results (1-50) |
### check_availability
Check item-level availability for a book.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| biblio_id | number | yes | Biblio ID from search results |
## Development
```bash
npm run dev # Run with tsx (hot reload)
npm test # Run tests
npm run build # Compile TypeScript
```
TDQS
Scored across 2 tools
The two tools have completely distinct purposes: search_books retrieves bibliographic records, while check_availability checks item status. There is no overlap, making tool selection unambiguous.
Both tool names follow the same verb_noun snake_case pattern: search_books and check_availability. The naming is consistent and intuitively indicates each tool's action and target.
With only 2 tools, the set feels thin but is appropriate for a narrowly scoped discovery and availability-checking service. It is not excessive, but the small number limits the server's overall utility.
The search-then-check-availability workflow is fully covered with no dead ends. A minor gap is the absence of a direct fetch-by-ID tool for full bibliographic details, but the search results likely provide sufficient information for the core use case.