{"id":"f668c415-1018-4ada-ab7e-fca4e90c0377","slug":"b2match-mcp","kind":"mcp","name":"b2match-mcp","summary":"Read-only MCP server for the B2match event and matchmaking platform","owner":"barzoj","repoUrl":"https://github.com/barzoj/b2match-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-19T11:18:55.000Z","addedAt":"2026-10-23T08:58:56.971Z","logoUrl":"https://avatars.githubusercontent.com/u/1120722?u=4ab1ab8ea6c078711432a310d0f5c1b7e6b96502&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","memory-knowledge"],"tags":["events","matchmaking","b2match"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T01:10:06.212Z","sample":false,"url":"https://conduits.dev/tools/b2match-mcp","language":"TypeScript","transports":["stdio"],"install":{"npm":"b2match-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# b2match-mcp\n\n[![CI](https://github.com/barzoj/b2match-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/barzoj/b2match-mcp/actions/workflows/ci.yml)\n[![Coverage](https://codecov.io/gh/barzoj/b2match-mcp/graph/badge.svg)](https://codecov.io/gh/barzoj/b2match-mcp)\n[![npm version](https://img.shields.io/npm/v/b2match-mcp)](https://www.npmjs.com/package/b2match-mcp)\n[![License: MIT](https://img.shields.io/npm/l/b2match-mcp)](LICENSE)\n[![Node.js](https://img.shields.io/node/v/b2match-mcp)](https://nodejs.org/)\n[![ToolSDK MCP Registry](https://badges.toolsdk.ai/badge/b2match-mcp)](https://toolsdk-ai.github.io/toolsdk-mcp-registry/#b2match-mcp)\n\nRead-only MCP server for the [B2match](https://www.b2match.com/) event and matchmaking platform.\n\nThis package is designed to be run locally by the user via `npx` and stdio MCP transport.\n\n**Disclaimer:** This project is unofficial and is not affiliated with, endorsed by, or supported by B2match. It uses B2match's undocumented web GraphQL API, so field availability can change without notice. Use it in accordance with [B2match's Terms of Service](https://www.b2match.com/) and GDPR. Participant profiles can be other people's personal data — keep exports local, respect each event's visibility rules, and do not harvest or republish personal data.\n\n## Read-only and privacy guarantees\n\n- The MCP server sends only GraphQL `query` operations. Mutations and subscriptions are parsed and rejected before any network call.\n- Known \"read-looking\" write operations are explicitly blocked, including profile-view, mark-as-read, session-attendance, and bookmark mutations.\n- B2match can still update its own read/seen counters when certain query fields are selected. See [Server-side side effects](#server-side-side-effects).\n- It never calls Plausible, Sentry, Google Analytics, HubSpot, LinkedIn pixel, or any non-B2match analytics endpoint.\n- It makes no external calls other than `https://api.b2match.com/v4/query` and the B2match Google login URL opened by the CLI.\n- No telemetry or analytics are collected by this package.\n- Tokens are never printed by tools or status commands.\n- Tokens are stored in the OS keychain when available, otherwise in a `0600` config file.\n\n## Install / run\n\nRequires Node.js 22 or newer. On macOS with Apple Silicon, the recommended install path is `npx`; no native build step is required for the auth storage path.\n\n```bash\nnpx -y b2match-mcp\n```\n\nFrom a checkout:\n\n```bash\nnpm install\nnpm run build\nnode dist/cli.js\n```\n\n## MCP client config\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"b2match\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"b2match-mcp\"]\n    }\n  }\n}\n```\n\n### Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"b2match\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"b2match-mcp\"]\n    }\n  }\n}\n```\n\n### VS Code\n\nAdd to `.vscode/mcp.json` or user MCP settings:\n\n```json\n{\n  \"servers\": {\n    \"b2match\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"b2match-mcp\"]\n    }\n  }\n}\n```\n\nFor local development from this checkout:\n\n```json\n{\n  \"mcpServers\": {\n    \"b2match\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/b2match-mcp/dist/cli.js\"]\n    }\n  }\n}\n```\n\n## Authentication\n\nPublic event data works anonymously. Personal data such as viewer profile, active events, meetings, schedule, conversations, notifications, and availability requires a locally stored B2match session token.\n\n### macOS / Linux login\n\n```bash\nb2match-mcp login https://www.b2match.com/e/<event-slug>\n# or: npx b2match-mcp login https://www.b2match.com/e/<event-slug>\n```\n\nThe default command:\n\n1. Resolves the event anonymously and asks B2match for its Google login URL.\n2. Launches your installed Chrome, Chromium, Edge, or Brave as a separate process.\n3. Uses a dedicated persistent profile under the tool config directory, not your everyday browser profile.\n4. Opens a remote-debugging port on `127.0.0.1` for that dedicated profile only (not your everyday browser). The port is closed when login finishes or times out.\n5. Lets you complete Google sign-in and 2FA by hand. The CLI does not fill any form.\n6. Waits for a JWT on the event tab URL (`www.b2match.com/e/<slug>?token=…`) or the event session cookie, validates it with a cheap viewer query, stores it, and closes that browser window. Chrome can 404 the post-Google event page before a cookie is set; the URL token is the path that works in that case.\n\nRepeat logins are usually one click because the dedicated profile keeps the Google session.\n\nmacOS may show a Keychain access prompt the first time the CLI stores or reads the token. Approve access for `b2match-mcp`/your terminal if you want Keychain storage. If access is denied or Keychain is unavailable, the CLI falls back to a private config file.\n\n### Paste-only / environment token\n\nUse these only when the dedicated browser flow cannot run:\n\n```bash\nb2match-mcp login --paste\n# or: npx b2match-mcp login --paste\nB2MATCH_TOKEN='<session-cookie-value>' b2match-mcp\n```\n\n`B2MATCH_TOKEN` is used in memory and is not persisted. Do not pass tokens on the command line; that leaks them into shell history.\n\n### Status / logout\n\n```bash\nb2match-mcp status\nb2match-mcp logout\nb2match-mcp logout --all\n```\n\n`logout` removes the stored B2match token only. `logout --all` also deletes the dedicated browser profile.\n\n### Dedicated browser profile\n\nLogin uses a dedicated Chromium profile at `~/.config/b2match-mcp/browser-profile` (or `$B2MATCH_MCP_CONFIG_DIR/browser-profile` / `$XDG_CONFIG_HOME/b2match-mcp/browser-profile`). That profile keeps the Google session, so a later `login` is usually one click.\n\nTo wipe the Google session as well as the stored B2match token:\n\n```bash\nb2match-mcp logout --all\n```\n\nTo delete only the profile and keep the stored token:\n\n```bash\nrm -rf ~/.config/b2match-mcp/browser-profile\n```\n\n`logout` without `--all` keeps the profile so the next login can reuse Google.\n\n### Storage locations\n\n- macOS: login Keychain via `/usr/bin/security` (`b2match-mcp` service, `default` account). After each save the CLI reads the item back; if the secret is missing or wrong it falls back to the private file and prints `keychain read-back failed, stored in file`.\n- Linux: `secret-tool` / libsecret when installed and unlocked.\n- Windows: private fallback file.\n- Fallback file: `$B2MATCH_MCP_CONFIG_DIR/auth.json`, `$XDG_CONFIG_HOME/b2match-mcp/auth.json`, or `~/.config/b2match-mcp/auth.json`, written with `0600` permissions.\n- `b2match-mcp status` reports `source: \"keychain-unreadable\"` (with a re-login hint) when a Keychain item exists but is empty or unreadable, instead of pretending you are logged out with `source: \"none\"`.\n- Dedicated browser profile: `~/.config/b2match-mcp/browser-profile` (same config directory).\n\nIf a token is a JWT, the CLI records its `exp` claim as `expiresAt`. B2match also has opaque tokens, in which case lifetime cannot be known locally. A 401 on an authenticated viewer check is reported as invalid/expired and remembered for the process. Public tools then continue anonymously without deleting the stored token.\n\n### Troubleshooting login\n\n- **No supported browser found:** install Chrome, Chromium, Edge, or Brave, or use `b2match-mcp login --paste`.\n- **Google blocks the window:** finish sign-in in the dedicated window if possible; otherwise use `--paste`.\n- **Timeout / 404 after Google:** the CLI also reads a JWT from the event tab URL if Chrome 404s before a cookie is set. Finish sign-in and wait; or use `--paste`.\n- **Keychain prompt denied:** run `b2match-mcp logout`, then `login` again and approve the prompt; or set `B2MATCH_MCP_DISABLE_KEYCHAIN=1` to use the private file fallback.\n- **`status` shows `keychain-unreadable`:** the Keychain item is empty or corrupt and no usable `auth.json` was found. Run `b2match-mcp logout` then `login` again. If a file token still works, `status` uses `source: \"file\"` and sets a `warning` about the Keychain item instead.\n- **Wrong/expired token:** run `b2match-mcp logout`, sign in again, and repeat `login`.\n\n## Tools\n\nPublic/anonymous:\n\n- `get_event` - event metadata, dates, registration window, login methods, and navigation. Numeric ids and slugs return the same fields.\n- `list_participants` - compact participant summaries with pagination and optional search. Set `detail=true` for the fuller list payload.\n- `get_participant` - one participant profile, without firing profile-view tracking.\n- `list_organisations`, `get_organisation` - organisation/participation pages. Menu paths such as `/components/<id>` are resolved automatically.\n- `list_opportunities`, `get_opportunity` - marketplace entries. Menu paths are resolved automatically; unknown opportunities return an MCP not-found error.\n- `get_agenda`, `get_session`, `list_session_attendees`, `list_speakers`.\n\nAuthenticated:\n\n- `auth_status`\n- `list_my_events`\n- `my_participation`\n- `my_schedule`\n- `my_meetings` - meetings by status; unfiltered responses use a compact availability summary unless `detail=true`\n- `my_availability` - merged free ranges per day by default; `detail=true` for the full timeslot grid\n- `find_meeting_slots`\n- `meeting_recommendations`\n- `list_conversations` - last-message previews; does not mark conversations as read\n- `get_conversation` - disabled by default because fetching messages marks the conversation as read; see side effects\n- `list_notifications` - unread/unseen counters by default; the full list resets unseen\n\nOptional raw query:\n\n- `graphql_read` is registered only when `B2MATCH_ALLOW_RAW=1`. It still rejects non-query operations and, unless `B2MATCH_ALLOW_SIDE_EFFECT_READS=1`, queries that select `messagesV2` or the notification list.\n\n## Server-side side effects\n\nThis client never sends B2match mutations such as `MarkConversationAsSeen` or `ReadNotification`. B2match can still mutate its own read/seen state when a **query** selects certain fields:\n\n- `get_conversation` (`messagesV2`) marks that conversation as read (unread-conversations count decreases).\n- `list_notifications` with the `notifications(...)` list field resets the unseen counter (unseen → 0). The unread counter is unchanged. Fetching `notificationsCounter` alone does not reset unseen.\n- `list_conversations` (including `lastMessageV2`) has no known side effects.\n\nGating:\n\n- Default `list_notifications` returns only `unread`/`unseen` counters.\n- `get_conversation` and the full notification list require `B2MATCH_ALLOW_SIDE_EFFECT_READS=1` **and** an explicit tool argument (`acknowledge_marks_read` / `acknowledge_marks_seen`).\n- `graphql_read` rejects queries that select `messagesV2` or the `notifications` list unless the same env var is set.\n\nUse `list_conversations` when you only need the last message.\n\nEach event-scoped tool accepts a current event URL (`https://www.b2match.com/e/<slug>`), a legacy event URL (`https://<slug>.b2match.io`), a bare slug, or a numeric event id.\n\nAuthenticated tools return an MCP error when no token is stored, with instructions to log in. They say the token is invalid or expired only after a stored token receives HTTP 401.\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for lint, format, coverage, Conventional Commits, and the read-only guard.\n\nLive smoke test against a public event (opt-in, not run in CI):\n\n```bash\nB2MATCH_LIVE_SMOKE=1 B2MATCH_SMOKE_EVENT='https://www.b2match.com/e/<event-slug>' npm test -- tests/live-smoke.test.ts\n```\n\nThe smoke test is skipped unless both environment variables are set.\n\n## Publishing\n\nReleases are cut by Release Please from Conventional Commits on `main`. The same workflow (`.github/workflows/release-please.yml`) publishes with `npm publish --provenance --access public` when a release is created (OIDC trusted publishing only — no `NODE_AUTH_TOKEN`). Provenance requires a public repo. Configure npm trusted publishing against workflow `release-please.yml`. To republish an existing tag: `gh workflow run release-please.yml -f publish_tag=vX.Y.Z`. `.github/workflows/publish.yml` is a tip-of-branch manual republish only.\n\n## Verification status\n\nVerified in this repo:\n\n- TypeScript build and unit tests.\n- Query-only enforcement, event identifier parsing, cookie-name helpers, dedicated-browser launch args, section-path resolution, compact participant summaries, and 401/auth-error policy.\n- Packed CLI `--help` / `status`.\n- Opt-in anonymous live smoke that exercises every public tool when `B2MATCH_SMOKE_EVENT` is provided.\n\nRequires a real login on a real machine:\n\n- Dedicated-profile Google login, Keychain prompt, URL-token or cookie capture.\n- Authenticated tools: `list_my_events`, `my_participation`, schedule, meetings, availability, meeting slots, recommendations, conversations, and notifications.\n\n## License\n\nMIT.\n"}