steveclarke/mcp-superthread-plus

MCP Superthread Plus Server

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.

Table of Contents

• MCP Superthread Plus Server
  • Table of Contents
  • Features
  • ⚠️ Important: Pre-Release Software
  • Installation
    • Getting Your API Key
  • Configuration
    • Selective Tool Enabling
    • Smart Card Positioning
  • Available Tools
    • Users & Workspace Management
    • Card Management
    • Tag Management
    • Project Management (Roadmap)
    • Board Management
    • Sprint Management
    • Space Management
    • Page Management
    • Note Management
    • Comments & Collaboration
    • Search
  • Usage Examples
    • Initial Setup - Discover Your Workspaces
    • Create Workspace Structure
    • Task Creation from Requirements
    • Manage Cards with Checklists
    • Collaborate with Comments
  • Requirements
  • Development
    • Setup
    • Commands
    • Running Locally
    • Architecture
  • Contributing
  • License

Features

• 📋 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

⚠️ Important: Pre-Release Software

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.

Installation

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+

Getting Your API Key

1. Log into Superthread → Settings & Preferences → Account → API Access
2. Create token
3. Add to your MCP config above

Configuration

All configuration is done via environment variables:

Selective Tool Enabling

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

Smart Card Positioning

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

Available Tools

Users & Workspace Management

Card Management

Note: All card tools use batch operations with array parameters. Always pass arrays, even for single operations.

Tag Management

Note: All tag tools use batch operations with array parameters. Always pass arrays, even for single operations.

Note: Tag management tools use undocumented API endpoints discovered via browser network inspection.

Project Management (Roadmap)

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.

Board Management

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.

Sprint Management

Note: Sprint get operations use batch operations with array parameters. Always pass arrays, even for single operations. Available batch tool: sprint_get.

Space Management

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.

Page Management

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.

Note Management

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.

Comments & Collaboration

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.

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.).

Search

Usage Examples

Initial Setup - Discover Your Workspaces

User: Get my Superthread account info
AI: *calls user_get_my_account*
→ Your account: user@example.com
→ Workspaces available:
  - Main Team 
  - Side Project

Create Workspace Structure

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

Task Creation from Requirements

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)

Manage Cards with Checklists

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

Collaborate with Comments

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

Requirements

• Node.js 22+
• Superthread account with API access
• Personal Access Token from Superthread account settings

Development

Setup

git clone https://github.com/steveclarke/mcp-superthread-plus.git
cd mcp-superthread-plus
pnpm install
pnpm run build

Commands

# 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 format

Running Locally

Configure 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"
      }
    }
  }
}

Architecture

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 for detailed architectural information and for API terminology mapping.

Important notes: See for information about API quirks, limitations, and undocumented endpoints.

Contributing

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

License

MIT