Threads MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Threads MCP Server show my active threads and suggest what I should work on next"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Threads MCP Server
MCP server exposing Threads CLI data and operations via the Model Context Protocol.
Installation
cd threads-mcp
npm install
npm run buildUsage
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 onlyTesting with MCP Inspector
npx @modelcontextprotocol/inspector node dist/server.jsResources
URI | Description |
| All threads |
| Active threads only |
| Hot/warm temperature threads |
| Single thread by ID |
| All containers |
| Single container by ID |
| All groups |
| Single group by ID |
| Entities in a group |
| Full hierarchy tree |
| Suggested next action |
| Progress log for a thread |
Tools
Thread Management
Tool | Description |
| Create a new thread |
| Update thread properties |
| Archive a thread (with optional cascade) |
| Permanently delete a thread |
| Get thread by ID or name |
Progress Tracking
Tool | Description |
| Add progress note to a thread |
| Get progress history |
| Edit a progress entry |
| Delete a progress entry |
Organization
Tool | Description |
| Create organizational container |
| Update container properties |
| Delete a container |
| Create a group |
| Update group properties |
| Delete a group |
| Set entity parent |
| Move entity to group |
| Get immediate children |
| Get path to root |
| Get full subtree |
Query & Search
Tool | Description |
| List threads with filters |
| List containers with filters |
| List all groups |
| Full-text search |
| Suggest next thread to work on |
| Get complete hierarchy |
| Get any entity by ID/name |
| Get container by ID/name |
| 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 operationsData 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 nextReview active work
1. Read threads://threads/active resource
2. Or use list_threads with status: "active"
3. Use list_progress to see recent updatesOrganize existing threads
1. Use create_group to create organizational groups
2. Use move_to_group to assign threads
3. Use set_parent to build hierarchyLicense
MIT
Available Tools
29 toolsadd_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
Scored across 29 tools
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.
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.
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.
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
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Remote MCP server to read and edit GanttFather projects: tasks, dates, dependencies, critical path.