A community-maintained MCP server for Superthread, a powerful project management platform. This server enables AI assistants to manage cards, boards, documentation, and more through natural conversation—perfect for teams using AI to streamline project setup, task creation from requirements, and workspace automation.
- MCP Superthread Plus Server
- 📋 Card Management - Create and manage cards with full workflow control (tags, checklists, relationships, assignments)
- 📊 Boards & Spaces - Organize work with customizable boards and organizational spaces
- 🗺️ Roadmap Projects - Plan and track large initiatives (epics)
- 📝 Documentation - Create and maintain pages
- 💬 Collaboration - Thread discussions on cards and pages with comments
- 🔍 Search - Find anything across all entities
- 🎯 Meeting Notes - Manage meeting notes and transcriptions
This is very much a work in progress. Please read this carefully before using:
-
Interim Solution: Superthread has an official MCP server which they're actively developing. Our goal is to provide a more complete toolset with full read/write API access until their official server expands. We are not trying to replace their official server—we're confident they're building it out—we just wanted more comprehensive functionality now. This is something to use in the meantime.
-
Not Production-Ready: This server is not yet at version 1.0 and should be used with caution. It may never reach version 1.0 as Superthread continues to expand their official MCP server.
-
Unofficial & Independent: This is a community project and is not officially affiliated with or endorsed by Superthread.
-
Direct API Passthrough: This server makes direct API calls to the Superthread API and returns all data exactly as received. We do not perform any caching, data reduction, or transformation. This means responses can be large and may impact performance.
-
Use at Your Own Risk: While we've taken reasonable security precautions, this is experimental software. Test thoroughly in non-critical environments before relying on it for important workflows.
-
Limited Support: This is a community project maintained in spare time. Issues and pull requests are welcome.
Bottom line: If you need something stable and production-ready, wait for Superthread's official solution. If you need functionality now and understand the risks, this server aims to help bridge the gap.
Add to your MCP settings file (e.g., Claude Desktop config):
{
"mcpServers": {
"superthread": {
"command": "npx",
"args": ["-y", "mcp-superthread-plus"],
"env": {
"SUPERTHREAD_API_KEY": "your-api-key-here"
}
}
}
}Requirements: Node.js 22+
- Log into Superthread → Settings & Preferences → Account → API Access
- Create token
- Add to your MCP config above
All configuration is done via environment variables:
| Variable | Required | Default | Description |
|---|---|---|---|
SUPERTHREAD_API_KEY |
✅ Yes | - | Personal Access Token from Superthread account |
SUPERTHREAD_API_BASE_URL |
No | https://api.superthread.com/v1 |
API endpoint (only change for testing) |
SUPERTHREAD_ENABLED_TOOLS |
No | (all enabled) | Comma-separated list of tool domains to enable. If not set or empty, ALL tools are enabled. Available domains: users, cards, boards, projects, spaces, sprints, pages, comments, notes, tags, search |
SUPERTHREAD_LISTS_ADD_TO_TOP |
No | (none) | Comma-separated list of list name patterns for smart positioning. Cards moved/created in matching lists are positioned at top (position 0). Supports wildcards (*). Example: "Done,Complet*,*finished,*archive*" |
By default, all tool domains are enabled when SUPERTHREAD_ENABLED_TOOLS is not set. This ensures backward compatibility and full functionality out of the box.
To reduce tool clutter in your AI client, you can explicitly specify which domains to enable. Only the domains you list will be enabled - all others will be disabled.
Enable only cards and boards:
{
"mcpServers": {
"superthread": {
"command": "npx",
"args": ["-y", "mcp-superthread-plus"],
"env": {
"SUPERTHREAD_API_KEY": "your-api-key-here",
"SUPERTHREAD_ENABLED_TOOLS": "cards,boards"
}
}
}
}Enable most tools except notes and tags:
{
"env": {
"SUPERTHREAD_API_KEY": "your-api-key-here",
"SUPERTHREAD_ENABLED_TOOLS": "users,cards,boards,projects,spaces,sprints,pages,comments,search"
}
}Important:
- Not set or empty = All domains enabled (full functionality)
- Set to specific domains = Only those domains enabled, all others disabled
- This is backward compatible - existing configs without this setting will continue to work with all tools enabled
By default, newly created or moved cards are added to the bottom of a list. While this works well for most lists (like "Backlog" or "To Do"), it's problematic for completion lists like "Done" or "Archived" where you typically want to see the most recently completed items at the top. Without smart positioning, recent completions get buried at the bottom, making it harder to track what was just finished.
Configure lists where cards should automatically be positioned at the top using
SUPERTHREAD_LISTS_ADD_TO_TOP:
{
"env": {
"SUPERTHREAD_API_KEY": "your-api-key-here",
"SUPERTHREAD_LISTS_ADD_TO_TOP": "Done,Completed,Finished"
}
}Features:
- Wildcard support: Use
*for pattern matching (e.g.,"Done,Complet*,*finished,*archive*") - Case-insensitive: Matches "done", "Done", "DONE" equally
- Comma escaping: Use backslash for list names with commas (e.g.,
"Tasks\\, Urgent") - LLM override: Explicit position parameter in tools always takes precedence
- Graceful fallback: If board/sprint fetch fails, cards use default positioning
| Tool | Description |
|---|---|
user_get_my_account |
Get current user account info and workspace memberships |
user_get_members |
List all members of a workspace |
Note: All card tools use batch operations with array parameters. Always pass arrays, even for single operations.
| Tool | Description |
|---|---|
card_create |
Create one or more cards (batch operation) |
card_update |
Update one or more cards (batch operation) |
card_get |
Get details for one or more cards (batch operation) |
card_delete |
Delete one or more cards permanently (batch operation) |
card_duplicate |
Clone one or more existing cards (batch operation) |
card_get_assigned |
Get cards assigned to a specific user |
card_add_related |
Create card relationships in batch (blocks, related, etc.) |
card_remove_related |
Remove card relationships in batch |
card_get_tags |
List all available tags in workspace |
card_add_tags |
Add existing tags to a card (supports array via ids) |
card_remove_tag |
Remove tags from cards in batch |
card_add_member |
Assign members to cards in batch |
card_remove_member |
Remove members from cards in batch |
card_create_checklist |
Create checklists on cards in batch |
card_update_checklist |
Update checklist titles in batch |
card_delete_checklist |
Delete checklists from cards in batch |
card_add_checklist_item |
Add items to checklist in batch (supports checked param) |
card_update_checklist_item |
Update checklist items in batch (check/uncheck, edit text) |
card_delete_checklist_item |
Delete checklist items in batch |
Note: All tag tools use batch operations with array parameters. Always pass arrays, even for single operations.
| Tool | Description |
|---|---|
tag_create |
Create one or more tags (batch operation) |
tag_update |
Update one or more tags (batch operation) |
tag_delete |
Delete one or more tags permanently (batch operation) |
Note: Tag management tools use undocumented API endpoints discovered via browser network inspection.
Note: All project tools use batch operations with array parameters. Always pass arrays, even for single operations. Available batch tools: project_get, project_create, project_update, project_delete, project_add_related, project_remove_related.
| Tool | Description |
|---|---|
project_get_all |
List all roadmap projects (epics) |
project_get |
Get one or more projects (batch operation) |
project_create |
Create one or more projects (batch operation) |
project_update |
Update one or more projects (batch operation) |
project_delete |
Delete one or more projects (batch operation) |
project_add_related |
Link cards to projects (batch operation) |
project_remove_related |
Remove card-project links (batch operation) |
Note: All board tools use batch operations with array parameters. Always pass arrays, even for single operations. Available batch tools: board_get, board_create, board_update, board_delete, board_create_list, board_update_list, board_delete_list.
| Tool | Description |
|---|---|
board_get_all |
List all boards in a space |
board_get |
Get one or more boards (batch operation) |
board_create |
Create one or more boards (batch operation) |
board_update |
Update one or more boards (batch operation) |
board_duplicate |
Clone an existing board |
board_delete |
Delete one or more boards (batch operation) |
board_create_list |
Create one or more lists (batch operation) |
board_update_list |
Update one or more lists (batch operation) |
board_delete_list |
Delete one or more lists (batch operation) |
Note: Sprint get operations use batch operations with array parameters. Always pass arrays, even for single operations. Available batch tool: sprint_get.
| Tool | Description |
|---|---|
sprint_get_all |
List all sprints for a space |
sprint_get |
Get one or more sprints (batch operation) |
Note: All space tools use batch operations with array parameters. Always pass arrays, even for single operations. Available batch tools: space_get, space_create, space_update, space_delete, space_add_member, space_remove_member.
| Tool | Description |
|---|---|
space_get_all |
List all spaces (organizational containers) |
space_get |
Get one or more spaces (batch operation) |
space_create |
Create one or more spaces (batch operation) |
space_update |
Update one or more spaces (batch operation) |
space_delete |
Delete one or more spaces (batch operation) |
space_add_member |
Add members to spaces (batch operation) |
space_remove_member |
Remove members from spaces (batch operation) |
Note: All page operations use batch operations with array parameters. Always pass arrays, even for single operations. Available batch tools: page_get, page_create, page_update, page_archive, page_delete.
| Tool | Description |
|---|---|
page_get |
Get one or more pages (batch operation) |
page_create |
Create one or more pages (batch operation) |
page_update |
Update one or more pages (batch operation) |
page_get_all |
List all pages in workspace |
page_duplicate |
Clone an existing page |
page_archive |
Archive one or more pages (batch operation) |
page_delete |
Delete one or more pages (batch operation) |
Note: All note operations use batch operations with array parameters. Always pass arrays, even for single operations. Available batch tools: note_get, note_create, note_delete.
| Tool | Description |
|---|---|
note_get |
Get one or more notes (batch operation) |
note_create |
Create one or more notes (batch operation) |
note_get_all |
List all notes |
note_delete |
Delete one or more notes (batch operation) |
Note: All comment tools use batch operations with array parameters. Always pass arrays, even for single operations. Available batch tools: comment_get, comment_create, comment_update, comment_delete, comment_reply, comment_update_reply, comment_delete_reply.
| Tool | Description |
|---|---|
comment_get |
Get one or more comments (batch operation) |
comment_create |
Create one or more comments (batch operation) |
comment_update |
Update one or more comments (batch operation) |
comment_delete |
Delete one or more comments (batch operation) |
comment_reply |
Reply to one or more comments (batch operation) |
comment_update_reply |
Update one or more replies (batch operation) |
comment_delete_reply |
Delete one or more replies (batch operation) |
comment_get_replies |
Get all replies to a comment |
Note: Comment tools support @mentions and HTML formatting. You can ask the AI to mention team members by name in comments and use HTML tags for rich formatting (headers, bold, italic, lists, links, etc.).
| Tool | Description |
|---|---|
search_get |
Search across boards, cards, pages, and more |
User: Get my Superthread account info
AI: *calls user_get_my_account*
→ Your account: [email protected]
→ Workspaces available:
- Main Team
- Side Project
User: Set up a new project workspace
AI: I'll create the structure:
1. Creating space "Q1 2025 Launch"...
2. Creating boards: Development, Design, Marketing...
3. Adding lists: To Do, In Progress, Review, Done...
✓ Workspace ready! Space ID: space_789
User: Create tasks for implementing user authentication
AI: *calls card_create with 5 cards in single batch operation*
✓ Created 5 tasks in one call:
- Set up auth provider (High priority, 8 points)
- Design login UI (Medium, 5 points)
- Implement JWT tokens (High, 8 points)
- Add password reset flow (Medium, 5 points)
- Write auth tests (Low, 3 points)
User: Add a checklist to card 123 for deployment steps, mark the first two as done
AI: *creates checklist, then adds 5 items with checked status in single batch call*
✓ Created deployment checklist with items:
- [x] Run tests
- [x] Update changelog
- [ ] Build production bundle
- [ ] Deploy to staging
- [ ] Deploy to production
User: Comment on card 456 and mention Sarah Chen: "Can you review the API changes?"
AI: *creates comment with mention*
✓ Added comment with mention to @Sarah Chen
- Node.js 22+
- Superthread account with API access
- Personal Access Token from Superthread account settings
git clone https://github.com/steveclarke/mcp-superthread-plus.git
cd mcp-superthread-plus
pnpm install
pnpm run build# Watch mode for development
pnpm run dev
# Build
pnpm run build
# Test
pnpm run test
# Lint
pnpm run lint
pnpm run lint:fix
# Format
pnpm run formatConfigure your MCP client to run from your local development directory:
{
"mcpServers": {
"superthread": {
"command": "node",
"args": ["/absolute/path/to/mcp-superthread-plus/dist/index.js"],
"env": {
"SUPERTHREAD_API_KEY": "your-token"
}
}
}
}This server uses a composition-based API client architecture with resource classes for each domain (cards, boards, projects, etc.). The client handles authentication, error handling, and automatic terminology mapping between Superthread's modern UI terms and legacy API terms.
For contributors: See docs/contributing/ARCHITECTURE.md for detailed architectural information and docs/contributing/API-REFERENCE.md for API terminology mapping.
Important notes: See docs/NOTES.md for information about API quirks, limitations, and undocumented endpoints.
Contributions welcome! We're focused on comprehensive API coverage with full read/write capabilities.
Areas for contribution:
- Enhanced response filtering and formatting
- Performance optimizations
- Documentation improvements
MIT