Skip to main content
Glama

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

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

Available Tools

29 tools
add_progressC

Add a progress note to a thread

Inputs: threadId (required), note (required), timestamp.

archive_threadC

Archive a thread (optionally with children)

Inputs: id (required), cascade.

create_containerC

Create a new container for organizing threads

Inputs: name (required), description, parentId, groupId, +1 more.

create_groupC

Create a new group for cross-cutting organization

Inputs: name (required), description.

create_threadC

Create a new thread for tracking an activity stream

Inputs: name (required), description, status, temperature, +5 more.

delete_containerC

Delete a container

Inputs: id (required).

delete_groupC

Delete a group

Inputs: id (required).

delete_progressC

Delete a progress entry

Inputs: threadId (required), progressId (required).

delete_threadC

Permanently delete a thread

Inputs: id (required).

edit_progressC

Edit an existing progress entry

Inputs: threadId (required), progressId (required), note (required).

get_ancestorsC

Get all ancestors of an entity (path to root)

Inputs: entityId (required).

get_childrenC

Get immediate children of an entity

Inputs: entityId (required).

get_containerC

Get a container by ID or name

Inputs: identifier (required).

get_entityC

Get any entity (thread or container) by ID or name

Inputs: identifier (required).

get_full_treeC

Get the complete hierarchy tree

Inputs: no named parameters.

get_groupC

Get a group by ID or name

Inputs: identifier (required).

get_next_actionB

Suggest the next thread to work on based on priority

Inputs: no named parameters.

get_subtreeC

Get the full subtree rooted at an entity

Inputs: entityId (required).

get_threadC

Get a single thread by ID or name

Inputs: identifier (required).

list_containersC

List containers with optional filtering

Inputs: groupId, parentId, tags, search.

list_groupsB

List all groups

Inputs: no named parameters.

list_progressC

Get progress history for a thread

Inputs: threadId (required), limit.

list_threadsC

List threads with optional filtering

Inputs: status, temperature, size, importance, +4 more.

move_to_groupC

Move a thread or container to a group

Inputs: entityId (required), groupId (required).

search_threadsC

Search threads and containers by text query

Inputs: query (required).

set_parentC

Set the parent of a thread or container

Inputs: entityId (required), parentId (required).

update_containerC

Update properties of a container

Inputs: id (required), name, description, tags.

update_groupC

Update properties of a group

Inputs: id (required), name, description.

update_threadC

Update properties of an existing thread

Inputs: id (required), name, description, status, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 29 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, such as create_thread vs. delete_thread or get_ancestors vs. get_children, but there is some overlap between get_entity and more specific getters like get_thread or get_container, which could cause minor confusion. Overall, the descriptions help clarify boundaries, but a few tools like get_entity might be redundant with others.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern throughout, such as create_thread, delete_container, update_group, and list_progress. All tools use snake_case without deviation, making them predictable and easy to understand. This consistency aids in agent selection and reduces cognitive load.

    Tool Count3/5

    With 29 tools, the count is borderline high for a thread management server, potentially feeling heavy and overwhelming for agents. While the tools cover many operations, some could be consolidated (e.g., multiple getters), making the set slightly over-scoped. It's not extreme, but it approaches the upper limit of reasonable.

    Completeness5/5

    The tool set provides complete CRUD and lifecycle coverage for threads, containers, groups, and progress notes, including creation, retrieval, updating, deletion, and organization (e.g., move_to_group, set_parent). No obvious gaps exist; agents can manage the entire hierarchy and workflow without dead ends, ensuring robust functionality.

    Related MCP Connectors