Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Bullet MCP show me my overdue tasks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Tool | Description |
| List entries with filtering by view ( |
| Create a task, note, or event. Omit |
| Get a single entry by UUID. Optionally expand collection/tags. |
| Update an entry's title. |
| Soft-delete an entry. |
| List all collections. Filter by archived status. |
| Get a single collection by UUID. |
| List all tags. Filter by archived status. |
| Get a single tag by UUID. |
Related MCP server: ticktick-cli
Go to bullet.to → Settings → API. Tokens start with blt_.
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 mcp add bullet -e BULLET_API_TOKEN=blt_your_token_here -- npx -y @davebream/bullet-mcpOpen 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"
}
}
}
}Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"bullet": {
"command": "npx",
"args": ["-y", "@davebream/bullet-mcp"],
"env": {
"BULLET_API_TOKEN": "blt_your_token_here"
}
}
}
}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 specspec/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.
Lefthook runs biome + gitleaks on commit, typecheck + tests on push:
lefthook installTest tools interactively with MCP Inspector:
BULLET_API_TOKEN=blt_xxx npx @modelcontextprotocol/inspector node dist/index.jsCreate a task, note, or event in Bullet. Set 'start' to schedule it on a date/time, or omit 'start' to put it in the inbox. Tasks track completion status, notes don't, events support timezone-aware datetimes.
Inputs: kind (required), title (required), start, period, +1 more. Returns: entry
Soft-delete an entry. Idempotent — succeeds even if already deleted.
Inputs: id (required). Returns: id, deleted
Get a single collection by ID.
Inputs: id (required). Returns: collection
Get a single entry by ID with full details. Use expand to include the collection and/or tags inline instead of just IDs.
Inputs: id (required), expand. Returns: entry
Get a single tag by ID.
Inputs: id (required). Returns: tag
List all collections (folders for organizing entries). Returns IDs needed for filtering entries by collection.
Inputs: archived. Returns: collections
Get scheduled entries for the current period plus any overdue items. Defaults to today. Use when the user asks what's on today, this week, this month, or wants a daily/weekly overview.
Inputs: expand, period. Returns: period, current, overdue
List tasks, notes, and events from Bullet. Two modes: (1) use 'view' for presets (inbox=unscheduled, overdue=past-due), or (2) use period+date for calendar queries. Each mode has different valid filters — see parameter descriptions. Returns paginated results; use cursor for next page.
Inputs: tag, date, kind, view, +6 more. Returns: cursor, entries, has_more
List all tags (labels for categorizing entries). Returns IDs needed for filtering entries by tag.
Inputs: archived. Returns: tags
Update an entry's title.
Inputs: id (required), title (required). Returns: entry
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 10 tools
Most tools have clear, distinct purposes: entry CRUD, collection read, tag read. The only potential confusion is between list_entries and list_current, as both return scheduled items, but the descriptions clarify list_current is for the current period/overdue while list_entries uses presets or calendar queries.
The naming follows a consistent verb_noun pattern for the majority of tools: list_entries, create_entry, get_entry, update_entry, delete_entry, list_collections, get_collection, list_tags, get_tag. The outlier is list_current, which uses an adjective instead of a noun, but it's still readable and not jarring.
With 10 tools, the server is well-scoped for its purpose of managing Bullet entries and referencing collections/tags. Each tool serves a distinct function and the count is within the ideal 3-15 range, making the surface neither too sparse nor overwhelming.
Entry CRUD is partially covered: create, list, get, and delete are present, but update_entry only changes the title, leaving no way to update status, schedule, or associations. Collections and tags are read-only, with no create/update/delete, so agents cannot manage these entities through the server, which is a significant functional gap.
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for generating rough-draft project plans from natural-language prompts.
Headless task management for bots, apps and AI agents. Remote MCP server, OAuth or access token.
