home / mcp / threads mcp server

Threads MCP Server

Exposes Threads CLI data and operations via the Model Context Protocol for programmatic access.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "joshuaramirez-threads-mcp": {
      "command": "node",
      "args": [
        "dist/server.js"
      ]
    }
  }
}

The Threads MCP Server exposes Threads CLI data and operations through the Model Context Protocol, letting you manage threads, containers, groups, and progress from MCP clients. It supports standard MCP tooling and integrates directly with the local Threads data store, enabling scripted workflows, automation, and CLI-style interactions from your preferred MCP client.

How to use

To use the Threads MCP Server, first install and build the server, then run it as a local process that MCP clients can connect to. You interact with the server by issuing MCP actions through your client to manage threads, containers, groups, and progress. You can also inspect the server during development to verify responses and behavior.

How to install

Prerequisites: Node.js and npm must be installed on your system.

Clone or download the project, then install dependencies and build the server.

cd threads-mcp
npm install
npm run build

Run and test the server locally

Run the server as a local process that MCP clients can connect to. The server is started by Node and uses the compiled distribution.

node dist/server.js

Configure your MCP client

Configure your MCP client to connect to the local server as a stdio MCP server. Use the command and path that correspond to your environment. The server can be started with the runtime command shown above, and your client will communicate over the standard MCP transport.

Data storage and compatibility

Data is stored in the Threads data location and is compatible with the Threads CLI. The MCP server reads and writes to the same data store, so operations performed through MCP mirror CLI behavior.

Example workflows

Create and track a project: use create_container to create a project container, create_thread to add threads under that container, log updates with add_progress, and use get_next_action to identify the next item to work on.

Review active work: view threads://threads/active or list_threads with a status filter, then inspect progress with list_progress.

Organize existing threads: create groups, move threads into groups, and establish hierarchy with set_parent.

Security and deployment notes

Keep your environment secure by restricting access to the local MCP server and protecting any tooling that interacts with your Threads data store. When deploying in shared environments, consider running the MCP server behind authentication and using scoped permissions for clients.

Notes

If you are developing or testing, you can also use the MCP Inspector to validate responses by running the server with a wrapper that exercises MCP endpoints.

Available tools

create_thread

Create a new thread within a container or project.

update_thread

Update properties of an existing thread.

archive_thread

Archive a thread, optionally cascading the action to related entities.

delete_thread

Permanently delete a thread.

get_thread

Retrieve a thread by ID or name.

add_progress

Add a progress note to a thread.

list_progress

Retrieve the progress history for a thread.

edit_progress

Edit an existing progress entry.

delete_progress

Delete a progress entry.

create_container

Create an organizational container.

update_container

Update container properties.

delete_container

Delete a container.

create_group

Create an organizational group.

update_group

Update group properties.

delete_group

Delete a group.

set_parent

Set the parent of an entity.

move_to_group

Move an entity into a group.

get_children

Get immediate children of an entity.

get_ancestors

Get the path from an entity to the root.

get_subtree

Get the full subtree under an entity.

list_threads

List threads with optional filters.

list_containers

List containers with filters.

list_groups

List all groups.

search_threads

Perform a full-text search on threads.

get_next_action

Suggest the next action for a thread.

get_full_tree

Get the complete hierarchy tree.

get_entity

Get any entity by ID or name.

get_container

Get a container by ID or name.

get_group

Get a group by ID or name.