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

threads-mcp