venunite-events 0.1.2

MCP client for VenuNite — hyperlocal event search across 50 states. Thin stdio↔HTTPS proxy for Claude Desktop and other stdio-only MCP clients.

venunite-events

MCP client for VenuNite — hyperlocal event search across 50 US states, powered by hand-built scrapers that cover the long tail that Ticketmaster / Eventbrite / SeatGeek miss (small clubs, breweries, churches, wineries, community centers).

This package is a thin stdio ↔ HTTPS bridge. Claude Desktop (and any MCP client that only speaks stdio) installs this package and points at it in the client's config; the bridge forwards MCP traffic to the hosted VenuNite MCP endpoint using your API key. Clients that natively speak streamable-HTTP (Claude.ai Custom Connectors, etc.) should connect to the hosted URL directly — they don't need this package.

Installation

Recommended — pipx (isolated venv, puts the CLI on your PATH):

brew install pipx            # macOS; otherwise follow https://pipx.pypa.io
pipx ensurepath              # adds ~/.local/bin to PATH (restart your shell after)
pipx install venunite-events

Why pipx instead of pip install: on modern macOS (Homebrew Python) and many Linux distros, pip install at the system level is blocked by PEP 668. pipx is the canonical path for Python CLIs — it creates a dedicated venv per tool, so no system-Python conflicts and no --break-system-packages footgun.

If you prefer a plain venv:

python3 -m venv ~/.venunite-events
~/.venunite-events/bin/pip install venunite-events
# Then use ~/.venunite-events/bin/venunite-events as the command in Claude Desktop's config.

Get an API key

Request a beta key by emailing [e-mail]. The key is shown once; store it in a password manager.

Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "venunite-events": {
      "command": "venunite-events",
      "env": {
        "VENUNITE_API_KEY": "vn_live_..."
      }
    }
  }
}

Claude Desktop may not inherit your shell PATH (pipx installs to ~/.local/bin). If the tool doesn't show up after restart, swap "command": "venunite-events" for the absolute path pipx printed at install time — commonly "/Users/YOUR_USERNAME/.local/bin/venunite-events" on macOS.

Restart Claude Desktop. The search_events tool appears in the MCP tool list in the bottom-right of the conversation input.

What you can ask

• "Any live music near Boulder this weekend under $30?"
• "What's happening at dive bars in Denver tonight?"
• "Queer-friendly events in Portland Oregon in the next two weeks"
• "Family-friendly trivia within 10 miles of Westminster CO"

The search_events tool supports: free-text vibe query, place name or lat/lng + radius, date window, cost bounds, category filter, and a canonical vibe-tag vocabulary. Strict tags (queer-friendly, family-friendly, age tiers) are hard filters — venues without the tag are excluded entirely, not down-ranked.

What data you get back

Each result is an event with venue metadata, start/end times, cost, category, ticket/website URLs, and a score breakdown (cosine similarity, tag overlap, distance decay, category match). Per-venue diversity is capped at 1 event per venue by default so a single busy venue doesn't dominate results — raise max_events_per_venue for "what's on at X" queries.

Environment

• VENUNITE_API_KEY required. Bearer token from your VenuNite account.
• VENUNITE_MCP_URL optional. Defaults to https://mcp.venunite.com/v1/mcp/. Override for self-hosted or staging.

Troubleshooting

Claude Desktop's per-server stderr lives at:

• macOS: ~/Library/Logs/Claude/mcp-server-venunite-events.log
• Windows: %APPDATA%\Claude\logs\mcp-server-venunite-events.log

If the tool doesn't appear after restart:

1. Check the log — missing VENUNITE_API_KEY prints to stderr
2. Verify the key works: curl -H "Authorization: Bearer $VENUNITE_API_KEY" -H "Accept: application/json, text/event-stream" https://mcp.venunite.com/v1/mcp/ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
3. Restart Claude Desktop fully (quit from the dock, don't just close the window)

Source

Everything — the scrapers, the retrieval core, the hosted MCP server, this proxy — is at github.com/isaacaskew/venunite-scrapers. Bug reports and feature requests welcome.

License

MIT.