Hyperspell MCP

🚀 Hyperspell Configuration Guide

This guide provides instructions on configuring Hyperspell, including setting up tokens, resource usage, and collection names. It also includes specific considerations for Claude Desktop and instructions on using the inspector.

🚀 Quick Start

Configuration Guide

• HYPERSPELL_TOKEN should be a valid user or application token (see Hyperspell documentation for how to obtain a user token).
• Some MCP clients do not support the resource feature (especially Claude Desktop), so we can expose it as a tool. Set HYPERSPELL_USE_RESOURCES to false (default) to expose everything as a tool, true to allow retrieving individual documents or listing collections as resources, or both to support both methods.
• Optional configuration: Set HYPERSPELL_COLLECTION to the name of the collection for target queries and adding data. If not set, the user's default collection will be used by default.

Notes for Claude Desktop

It should be noted that Claude requires an absolute path to uv, which can be found using the command which uv (usually located at ~/.local/bin/uv).

{
  "mcpServers": {
    "Hyperspell": {
      "command": "/path/to/uv",
      "args": [
        "run",
        "--with",
        "hyperspell",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "/path/to/hyperspell_mcp/server.py"
      ],
      "env": {
        "HYPERSPELL_TOKEN": "<Application or user token>",
        "USE_RESOURCES": "false"
      }
    }
  }
}

Using the Inspector

Create a .env file with the following content:

HYPERSPELL_TOKEN=...
HYPERSPELL_USE_RESOURCES=true

Then run the following command to start the inspector:

uv run mcp dev src/hyperspell_mcp/server.py