Metadata-Version: 2.4
Name: venunite-events
Version: 0.2.1
Summary: MCP client for VenuNite — hyperlocal event search across 50 states. Thin stdio↔HTTPS proxy for Claude Desktop and other stdio-only MCP clients.
Project-URL: Homepage, https://venunite.com
Author-email: Isaac Askew <isaac@venunite.com>
License: MIT
Keywords: claude,events,mcp,model-context-protocol,semantic-search,venunite
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications
Classifier: Topic :: Database :: Front-Ends
Requires-Python: >=3.10
Requires-Dist: anyio>=4.5
Requires-Dist: mcp>=1.27
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.isaacaskew/venunite-events -->

# venunite-events

MCP client for [VenuNite](https://venunite.com) — 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):

```bash
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](https://peps.python.org/pep-0668/). `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:

```bash
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 `isaac@venunite.com`. 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):

```json
{
  "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.

## 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)

## License

MIT.
