Threads MCP Server

MCP server exposing Threads CLI data and operations via the Model Context Protocol.

Installation

cd threads-mcp
npm install
npm run build

Usage

With Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "threads": {
      "command": "node",
      "args": ["C:/Users/joshu/Desktop/threads-mcp/dist/server.js"]
    }
  }
}

Development

npm run dev        # Run with tsx (no build needed)
npm run build      # Compile TypeScript
npm run start      # Run compiled version
npm run typecheck  # Type check only

Testing with MCP Inspector

npx @modelcontextprotocol/inspector node dist/server.js

Resources

URI	Description
threads://threads/list	All threads
threads://threads/active	Active threads only
threads://threads/hot	Hot/warm temperature threads
threads://threads/{id}	Single thread by ID
threads://containers/list	All containers
threads://containers/{id}	Single container by ID
threads://groups/list	All groups
threads://groups/{id}	Single group by ID
threads://groups/{id}/members	Entities in a group
threads://tree	Full hierarchy tree
threads://next	Suggested next action
threads://progress/{threadId}	Progress log for a thread

Tools

Thread Management

Tool	Description
create_thread	Create a new thread
update_thread	Update thread properties
archive_thread	Archive a thread (with optional cascade)
delete_thread	Permanently delete a thread
get_thread	Get thread by ID or name

Progress Tracking

Tool	Description
add_progress	Add progress note to a thread
list_progress	Get progress history
edit_progress	Edit a progress entry
delete_progress	Delete a progress entry

Organization

Tool	Description
create_container	Create organizational container
update_container	Update container properties
delete_container	Delete a container
create_group	Create a group
update_group	Update group properties
delete_group	Delete a group
set_parent	Set entity parent
move_to_group	Move entity to group
get_children	Get immediate children
get_ancestors	Get path to root
get_subtree	Get full subtree

Query & Search

Tool	Description
list_threads	List threads with filters
list_containers	List containers with filters
list_groups	List all groups
search_threads	Full-text search
get_next_action	Suggest next thread to work on
get_full_tree	Get complete hierarchy
get_entity	Get any entity by ID/name
get_container	Get container by ID/name
get_group	Get group by ID/name

Architecture

threads-mcp/
├── src/
│   ├── server.ts           # Entry point, stdio transport
│   ├── lib/
│   │   ├── threads-client.ts  # Wrapper for Threads storage
│   │   └── types.ts           # MCP-specific types
│   ├── resources/
│   │   ├── index.ts        # Resource registration
│   │   ├── threads.ts      # Thread resources
│   │   ├── containers.ts   # Container resources
│   │   └── groups.ts       # Group resources
│   └── tools/
│       ├── index.ts        # Tool registration
│       ├── thread-ops.ts   # Thread operations
│       ├── progress-ops.ts # Progress operations
│       ├── org-ops.ts      # Organization operations
│       └── query-ops.ts    # Query operations

Data Storage

Data is stored in ~/.threads/threads.json (same as Threads CLI). This server directly reads and writes to that file, maintaining full compatibility with CLI operations.

Example Workflows

Create and track a project

1. Use create_container to create "My Project"
2. Use create_thread to create threads under that container
3. Use add_progress to log updates as you work
4. Use get_next_action to see what to work on next

Review active work

1. Read threads://threads/active resource
2. Or use list_threads with status: "active"
3. Use list_progress to see recent updates

Organize existing threads

1. Use create_group to create organizational groups
2. Use move_to_group to assign threads
3. Use set_parent to build hierarchy

License

MIT