Use it from your terminal or your AI

polls is a web app first, but it also exposes a CLI and an MCP server so you can run it from your shell or wire it into Claude Code / any MCP-aware agent.

CLI — @basenull/poll

One-shot poll creation from your terminal. No install — just npx.

The convenience form

npx @basenull/poll "burrito vs pizza vs salad"
# https://polls.basenull.com/p/abc123 (printed on stdout, opens in your browser)
# admin: https://polls.basenull.com/a/...  (printed on stderr — keep this private)

Explicit options

npx @basenull/poll "What's for lunch?" -o burrito -o pizza -o salad

Attribute polls to your account

By default, the CLI creates anonymous polls (admin-by-URL, 7-day expiry). Pass an MCP token to attribute the poll to your basenull account so it shows up on your dashboard and follows your tier's caps.

POLLS_TOKEN=polls_xxx npx @basenull/poll "Title" -o a -o b
# or:
npx @basenull/poll --token=polls_xxx "Title" -o a -o b

Sign in and head to /dashboard/mcp to create a token. Same token works for both the CLI and the MCP server.

MCP — Claude Code & any MCP agent

polls exposes an HTTP MCP server. Wire it into your agent and Claude can create polls, cast votes, and read tallies on your behalf — from inside any conversation.

Step 1 — paste into ~/.claude/mcp.json (or project .claude/mcp.json)

{
  "mcpServers": {
    "polls": {
      "type": "http",
      "url": "https://polls.basenull.com/api/mcp",
      "headers": { "Authorization": "Bearer <paste-token-here>" }
    }
  }
}

Step 2 — drop this fragment into your CLAUDE.md / AGENTS.md

## polls.basenull.com

You have access to a polls MCP server. Use it whenever the user asks you to
"make a poll" or "vote on" something. Tools:

- create_poll(title, options[, description, is_private, listed_only, close_at_iso, required_responders])
- list_my_polls()
- get_poll(poll_id)
- vote(poll_id, option_id, status, voter_email)   // status is "yes" | "maybe" | "no"
- close_poll(poll_id)

Always share the participate_url with the user after creating a poll.

Tools the server exposes

  • create_poll(title, options[, …]) — returns poll_id and participate_url
  • list_my_polls() — every poll you own
  • get_poll(poll_id) — full details + current vote tallies
  • vote(poll_id, option_id, status, voter_email) — status is one of yes / maybe / no
  • close_poll(poll_id) — owner only, freezes votes

Sign in to create a token →

Need help? Email hello@basenull.com.
Docs · polls.basenull.com