homosaurus-mcp

Homosaurus MCP

An experimental MCP (Model Context Protocol) server connecting Claude to the Homosaurus V4 LGBTQ+ linked data vocabulary, developed to investigate the potential of large language models in subject analysis and authority control.

---

What This Server Does

Homosaurus MCP connects Claude Desktop to the Homosaurus vocabulary via two live APIs, allowing you to search and retrieve Homosaurus authority data directly within your AI-assisted cataloging workflow.

Once installed, you can ask Claude things like:

• "Search the Homosaurus for terms related to bisexuality"
• "Find the Homosaurus term for queer families"
• "What are the broader and narrower terms for 'Transgender people'?"
• "Retrieve the full record for this Homosaurus URI"

The server handles all the API calls, parses the responses, and returns structured data Claude can reason about.

---

Who This Is For

• Catalogers using Claude Desktop who want AI-assisted subject heading work grounded in real Homosaurus authority data
• Library and archives staff building or evaluating AI-assisted cataloging tools and workflows for LGBTQ+ materials
• Developers integrating Homosaurus vocabulary lookups into MCP-based systems

---

Tools

| Tool | Description | |------|-------------| | search_homosaurus | Search by string match, returns top 10 candidates with relevance scores. | | search_homosaurus_broad | Same search with a higher limit, returns top 25 candidates. | | get_homosaurus_term | Full term record by URI — preferred label, alt labels, scope note, broader/narrower/related terms. |

---

Notes on Search Behaviour

Search is handled by the NDE Termennetwerk Reconciliation Service API (W3C CG spec v0.2), which searches the Homosaurus vocabulary hosted by IHLIA. Results are scored by relevance and sorted in descending order. The match flag in results indicates whether the service considers a candidate a high-confidence exact match.

search_homosaurus_broad uses the same underlying search but requests 25 candidates instead of 10. Use it when exploring a concept area or when the standard search returns too few results.

Full record retrieval via get_homosaurus_term fetches the individual term JSON-LD directly from homosaurus.org. Broader, narrower, and related terms are returned as URI lists — pass each URI back to get_homosaurus_term to resolve labels if needed.

No local data is cached. Every tool call is a live network request. Search depends on termennetwerk-api.netwerkdigitaalerfgoed.nl; full record retrieval depends on homosaurus.org.

---

Installation

Requirements

• Python 3.11 or later
• Claude Desktop (or another MCP-compatible host)

Install from GitHub

Mac:

pip3 install git+https://github.com/msuicaut/homosaurus-mcp-server.git

Windows (Anaconda Prompt):

pip install git+https://github.com/msuicaut/homosaurus-mcp-server.git

Install from a local clone

git clone https://github.com/msuicaut/homosaurus-mcp-server.git
cd homosaurus-mcp-server
pip install -e .

On Windows with Anaconda, use Anaconda Prompt and add --break-system-packages if prompted.

---

Claude Desktop Configuration

After installation, add the server to your claude_desktop_config.json. Claude Desktop uses a restricted PATH that does not include the Python bin directory, so the full path to the command is required.

To find your exact path, run the following in Terminal (Mac) or Anaconda Prompt (Windows):

• Mac: which homosaurus-mcp
• Windows: where homosaurus-mcp

The examples below are illustrative only — your actual path will differ depending on your Python version and installation method.

Mac (example): ``json { "mcpServers": { "homosaurus": { "command": "/Library/Frameworks/Python.framework/Versions/3.13/bin/homosaurus-mcp" } } } ``

Windows/Anaconda (example): ``json { "mcpServers": { "homosaurus": { "command": "C:\\Users\\username\\anaconda3\\Scripts\\homosaurus-mcp.exe" } } } ``

Always replace the path with the actual output of the which or where command on your machine.

Finding your config file:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

After editing the config, quit Claude Desktop completely and reopen it. The Homosaurus tools will be available in your next conversation.

Verifying the installation

Once Claude Desktop is open, ask: "What Homosaurus tools do you have available?" — you should see all three tools listed.

---

Updating

Mac:

pip3 install --upgrade git+https://github.com/msuicaut/homosaurus-mcp-server.git

Windows (Anaconda Prompt):

pip install --upgrade git+https://github.com/msuicaut/homosaurus-mcp-server.git

After updating, restart Claude Desktop fully.

---

Troubleshooting

Tools not appearing in Claude Desktop

• Confirm the package installed without errors: pip show homosaurus-mcp-server
• Confirm the command is available: homosaurus-mcp --help (should start the server, not throw an error)
• Check that the config file path is correct for your OS
• Quit Claude Desktop fully (not just close the window) before reopening

Search returns an error

The search tool depends on the NDE Termennetwerk API. If the API is unavailable, tool calls will return a descriptive error message. Check your network connection and try again.

get_homosaurus_term returns an error

Confirm the URI is a valid homosaurus.org URI returned by a search tool. URIs from other vocabularies will be rejected.

Changes to server.py not taking effect

Python caches compiled bytecode in __pycache__ folders. After editing server.py, delete any __pycache__ folders in the package directory and restart Claude Desktop fully.

---

License

GPLv3. See LICENSE.

---

Development Note

The code in this project was developed in collaboration with Claude, Anthropic's AI assistant. The design decisions — including tool selection, API choice, and the application of cataloging practice to the server's behaviour — reflect the author's professional cataloging expertise. Claude handled the implementation of those decisions in Python.

---

Acknowledgement

This project makes use of the Homosaurus vocabulary provided by the Digital Transgender Archive and maintained at homosaurus.org. Search is provided by the NDE Termennetwerk, a service of the Dutch Digital Heritage Network (Netwerk Digitaal Erfgoed).

The project was inspired by and adapted from KL Tang's cataloger-mcp, extended here to apply to Homosaurus vocabulary lookup.