venunite-events

MCP client for VenuNite — hyperlocal event search across 50 US states, sourced from independent venue and community calendars with links back to the underlying event sources.

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. No key is required to try it. Clients that natively speak streamable HTTP should connect to the hosted URL directly — they don't need this package.

Fastest path: hosted MCP

In a client that supports remote MCP servers, connect this URL:

https://mcp.venunite.com/v1/mcp/

Anonymous search starts immediately. For MCP v1 clients that persist VenuNite's signed Mcp-Session-Id header or browser cookie, the trial allows 5 tool calls per minute and 10 per 24-hour transport session; a new initialization/restart can begin another session. Newer/sessionless clients may not retain that identifier, so the shared-network fair-use ceilings are the only universal anonymous abuse guarantee. A no-card free key is the portable option: 5/minute and 100/day per VenuNite account, shared by that account's keys.

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.

Optional: get a free API key

Create and copy a key at venunite.com/developers/keys. The key is shown once, so store it in a password manager. The same key automatically receives the right MCP allowance for your account:

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"
    }
  }
}

That configuration uses the anonymous trial. To use your free or paid allowance, add the optional key:

{
  "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 a ranked event with venue metadata, start/end times, cost, category, and the original event-source URL when available. Purchase-specific ticket destinations, internal request telemetry, and ranking diagnostics are intentionally omitted from the public MCP response. 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 optional. A free or paid key from your developer key page; omit it for anonymous access.
• VENUNITE_MCP_URL optional. Override the default hosted endpoint for staging or self-hosted development.

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 for a proxy or network error.
2. Verify anonymous initialization works: curl -X POST -H "Accept: application/json, text/event-stream" -H "Content-Type: application/json" 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. If you configured a key, verify it separately by adding -H "Authorization: Bearer $VENUNITE_API_KEY" to that command.
4. Restart Claude Desktop fully (quit from the dock, don't just close the window).

License

MIT.