Bullet MCP

MCP server for the Bullet API. Manage tasks, notes, and events from Claude Desktop, Claude Code, VS Code, Cursor, or any MCP client.

Types are generated from the OpenAPI spec. Tool input schemas use Zod that mirrors the API contract. Registration tests verify they stay in sync. The MCP server version matches the Bullet API version.

Tools

| Tool | Description | |---|---| | list_entries | List entries with filtering by view (inbox/overdue), period, date, status, kind, collection, or tag. Cursor pagination. | | create_entry | Create a task, note, or event. Omit start to place in inbox. | | get_entry | Get a single entry by UUID. Optionally expand collection/tags. | | update_entry | Update an entry's title. | | delete_entry | Soft-delete an entry. | | list_collections | List all collections. Filter by archived status. | | get_collection | Get a single collection by UUID. | | list_tags | List all tags. Filter by archived status. | | get_tag | Get a single tag by UUID. |

Setup

Get a Bullet API token

Go to bullet.to → Settings → API. Tokens start with blt_.

Claude Desktop

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

{
  "mcpServers": {
    "bullet": {
      "command": "npx",
      "args": ["-y", "@davebream/bullet-mcp"],
      "env": {
        "BULLET_API_TOKEN": "blt_your_token_here"
      }
    }
  }
}

Claude Code

claude mcp add bullet -e BULLET_API_TOKEN=blt_your_token_here -- npx -y @davebream/bullet-mcp

VS Code

Open MCP config (Ctrl+Shift+P → "MCP: Open User Configuration"):

{
  "servers": {
    "bullet": {
      "command": "npx",
      "args": ["-y", "@davebream/bullet-mcp"],
      "env": {
        "BULLET_API_TOKEN": "blt_your_token_here"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "bullet": {
      "command": "npx",
      "args": ["-y", "@davebream/bullet-mcp"],
      "env": {
        "BULLET_API_TOKEN": "blt_your_token_here"
      }
    }
  }
}

Development

bun install              # install dependencies
bun run test             # run all tests
bun run lint             # biome lint + format check
bun run typecheck        # type-check
bun run build            # compile to dist/
bun run generate         # regenerate types from OpenAPI spec

How it fits together

spec/openapi.json              ← source of truth (Bullet API contract)
  ↓ bun run generate
src/client/types.generated.ts  ← auto-generated types (don't edit)
src/client/types.ts            ← re-exports for convenience
src/client/api.ts              ← typed HTTP client
src/tools/definitions.ts       ← Zod schemas for MCP tool inputs
src/tools/entries.ts           ← pure handlers: (client, params) → string
src/tools/collections.ts
src/tools/tags.ts
src/tools/format.ts            ← pure formatters
src/index.ts                   ← MCP server wiring (only file with side effects)

Tool handlers are pure functions — pass in a client and params, get a string back. Tests use stub clients, no HTTP mocking.

Git hooks

Lefthook runs biome + gitleaks on commit, typecheck + tests on push:

lefthook install

Debugging

Test tools interactively with MCP Inspector:

BULLET_API_TOKEN=blt_xxx npx @modelcontextprotocol/inspector node dist/index.js

License

MIT