Skip to main content
Glama
Tree of Thoughts MCP Server

Tree of Thoughts MCP Server

by HefnySco

🌳 Tree of Thoughts (ToT) MCP Server

Tree of Thoughts (ToT) is a powerful reasoning framework that enables AI models to explore multiple solution paths systematically. Think of it as a decision tree for thoughtsβ€”your AI can generate different approaches, evaluate them, backtrack when stuck, and focus on the most promising paths. Perfect for complex problem-solving, strategic planning, and multi-step reasoning tasks.

Whether you're solving puzzles, planning projects, or exploring creative alternatives, ToT provides structured exploration with evaluation scores, pruning strategies, and persistent storage for tracking reasoning over time.

✨ Features

  • 🌲 Thought Trees - Create hierarchical thought structures with parent-child relationships

  • πŸ“Š Evaluation - Score thoughts to guide exploration toward promising paths

  • ↩️ Backtracking - Mark thought branches as pruned and explore alternatives

  • βœ‚οΈ Pruning - Automatically remove low-scoring branches

  • πŸ† Best Path Selection - Identify and select the most promising thoughts

  • πŸ’Ύ Persistent Storage - Save and load thought trees across sessions with atomic writes and error handling

  • πŸ“ˆ Statistics - Track tree metrics (depth, evaluations, pruning rates)

  • πŸ” Branching Strategies - Systematic exploration using BFS, DFS, beam search, and best-first search

  • πŸ€– LLM Integration - Optional LLM provider for automated thought generation with strict mode support

  • πŸ›‘οΈ Robust Traversal - Iterative implementations for handling very deep trees without recursion limits

  • βœ… Schema Validation - Input validation for all tool parameters

Related MCP server: Visum Thinker MCP Server

πŸš€ Installation

npm install
npm run build

βš™οΈ Configuration

Add to your MCP client configuration (e.g., mcp.json):

{
  "mcpServers": {
    "tot": {
      "command": "node",
      "args": ["/path/to/ToT-mcp/dist/index.js"],
      "env": {
        "TOT_STORAGE_PATH": "/path/to/ToT-mcp/tot-storage.json",
        "TOT_OUTPUT_DIR": "/path/to/ToT-mcp/output"
      }
    }
  }
}

🎯 Quick Start

Basic Example

Create a tree to solve a problem:

{
  "goal": "Solve the 24 game with numbers [3, 8, 8, 8]",
  "rootContent": "Start with the numbers 3, 8, 8, 8",
  "maxDepth": 5
}

Add child thoughts with different approaches:

{
  "treeId": "tree-123",
  "parentId": "thought-456",
  "content": "Try multiplying 8 * 8 = 64, then 64 / 8 = 8, then 8 * 3 = 24"
}

Evaluate thoughts to guide exploration:

{
  "treeId": "tree-123",
  "thoughtId": "thought-789",
  "score": 0.95,
  "reasoning": "This approach successfully reaches the target of 24"
}

LLM Provider Configuration

The server supports optional LLM integration for automated thought generation. To configure an LLM provider, modify the server instantiation in src/index.ts:

const llmProvider = {
  generateThoughts: async (prompt: string, count: number, context?: string): Promise<string[]> => {
    // Your LLM implementation here
    return Array.from({ length: count }, (_, i) => `Generated thought ${i + 1}`);
  }
};

const config = {
  llmProvider,
  strictLLM: false // Set to true to throw errors when LLM is not configured
};

const server = new ToTMCPServer(config);

Strict Mode: When strictLLM is set to true, the server will throw an error if generate_children is called without an LLM provider configured. This prevents accidental use of placeholder thoughts in production environments.

Using with LLM Providers

The ToT service includes LLM provider implementations in the src/llm-providers/ directory:

Mock LLM Provider - A simple mock implementation for testing:

import { MockLLMProvider } from './src/llm-providers/mock-llm-provider.js';

const llmProvider = new MockLLMProvider([
  'Consider exploring the most promising path first',
  'Try a different approach by breaking down the problem',
  'Evaluate the trade-offs between different solutions'
]);

const config = { llmProvider, strictLLM: false };
const service = new ToTService('./tot-storage.json', config);

Grok LLM Provider - Implementation using xAI's Grok API:

import { GrokLLMProvider } from './src/llm-providers/grok-llm-provider.js';

const apiKey = process.env.GROK_API_KEY;
const llmProvider = new GrokLLMProvider(apiKey);

const config = { llmProvider, strictLLM: true };
const service = new ToTService('./tot-storage.json', config);

Ollama LLM Provider - Local LLM support using Ollama:

import { OllamaLLMProvider } from './src/llm-providers/ollama-llm-provider.js';

const ollamaBaseUrl = process.env.OLLAMA_BASE_URL || 'http://localhost:11434';
const ollamaModel = process.env.OLLAMA_MODEL || 'llama2';
const llmProvider = new OllamaLLMProvider(ollamaBaseUrl, ollamaModel);

const config = { llmProvider, strictLLM: true };
const service = new ToTService('./tot-storage.json', config);

To use Ollama:

  1. Install and start Ollama: https://ollama.ai

  2. Pull a model: ollama pull llama2 (or any other model)

  3. Set environment variables:

    • LLM_PROVIDER_TYPE=ollama

    • OLLAMA_BASE_URL=http://localhost:11434 (optional, default)

    • OLLAMA_MODEL=llama2 (optional, default)

See src/llm-providers/grok-llm-provider.ts and src/llm-providers/ollama-llm-provider.ts for full implementations. Remember to never hardcode API keys - use environment variables or secure configuration management.

Generate and Evaluate in One Step

The generateChildrenAndEvaluate method combines thought generation with automatic evaluation:

// Generate children with a default score of 50
const children = await service.generateChildrenAndEvaluate({
  treeId: 'tree-123',
  parentId: 'thought-456',
  numChildren: 3
}, 50);

// Generate children and use LLM as judge for evaluation
const childrenWithJudge = await service.generateChildrenAndEvaluate({
  treeId: 'tree-123',
  parentId: 'thought-456',
  numChildren: 3
}, undefined, true);

This method requires an LLM provider to be configured.

πŸ› οΈ Available Tools

Tree Management

create_tree

Create a new Tree of Thoughts with a root thought and goal.

Parameters:

  • goal (string, required): The goal or problem this tree is solving

  • rootContent (string, required): The content of the root thought

  • maxDepth (number, optional): Maximum depth of the tree (default: 10)

  • metadata (object, optional): Optional metadata for the tree

get_tree

Get a tree by ID.

Parameters:

  • treeId (string, required): The ID of the tree to retrieve

list_trees

List all trees.

delete_tree

Delete a tree by ID.

Parameters:

  • treeId (string, required): The ID of the tree to delete

clear_tree

Clear a specific tree by ID.

Parameters:

  • treeId (string, required): The ID of the tree to clear

Thought Operations

add_child

Add a child thought to an existing thought.

Parameters:

  • treeId (string, required): The ID of the tree

  • parentId (string, required): The ID of the parent thought

  • content (string, required): The content of the child thought

  • metadata (object, optional): Optional metadata for the thought

evaluate_thought

Evaluate a thought with a score.

Parameters:

  • treeId (string, required): The ID of the tree

  • thoughtId (string, required): The ID of the thought to evaluate

  • score (number, required): The evaluation score (e.g., 0-1 or 0-100)

  • reasoning (string, optional): Optional reasoning for the evaluation

select_thought

Mark a thought as selected for further exploration.

Parameters:

  • treeId (string, required): The ID of the tree

  • thoughtId (string, required): The ID of the thought to select

backtrack

Backtrack from a thought, marking all descendants as pruned.

Parameters:

  • treeId (string, required): The ID of the tree

  • thoughtId (string, required): The ID of the thought to backtrack from

prune_tree

Prune thoughts below a certain evaluation threshold.

Parameters:

  • treeId (string, required): The ID of the tree

  • threshold (number, required): The evaluation threshold (thoughts below this will be pruned)

move_subtree

Move a subtree to a new parent within the same tree. Performs cycle detection, depth validation, and supports dry-run mode for safe preview.

Parameters:

  • treeId (string, required): The ID of the tree

  • subtreeRootId (string, required): The ID of the subtree root to move

  • newParentId (string, required): The ID of the new parent thought

  • dryRun (boolean, optional): If true, preview the move without making changes (default: false)

Returns:

  • valid (boolean): Whether the move is valid

  • errors (array): List of validation errors

  • movedCount (number): Number of thoughts that would be moved

  • newSubtreeRootDepth (number): New depth of the subtree root after move

  • warnings (array): List of warnings and recommendations

  • affectedThoughtIds (array): IDs of all thoughts in the subtree

Important Notes:

  • Cannot move the tree root (use create_tree to create a new tree instead)

  • Cannot move a subtree to create a cycle (new parent must not be a descendant of subtree root)

  • Move must not exceed the tree's maxDepth limit

  • Use dryRun: true to preview the move before executing

  • After moving, consider re-evaluating thoughts in their new context

  • This is a reasoning-layer operation for restructuring thought trees, distinct from Task Orchestrator's move_task which is for execution workflow management

Query Operations

get_thought

Get a specific thought by ID.

Parameters:

  • treeId (string, required): The ID of the tree

  • thoughtId (string, required): The ID of the thought to retrieve

get_tree_structure

Get the hierarchical structure of a tree.

Parameters:

  • treeId (string, required): The ID of the tree

get_best_thoughts

Get the best evaluated thoughts in a tree.

Parameters:

  • treeId (string, required): The ID of the tree

  • limit (number, optional): Maximum number of thoughts to return (default: 5)

get_tree_stats

Get statistics about a tree.

Parameters:

  • treeId (string, required): The ID of the tree

Returns:

  • totalThoughts: Total number of thoughts in the tree

  • evaluatedThoughts: Number of evaluated thoughts

  • selectedThoughts: Number of selected thoughts

  • prunedThoughts: Number of pruned thoughts

  • maxDepthReached: Maximum depth reached in the tree

  • averageEvaluation: Average evaluation score

System Operations

clear_tree

Clear a specific tree by ID.

Parameters:

  • treeId (string, required): The ID of the tree to clear

clear_strategy

Clear a specific strategy by ID.

Parameters:

  • strategyId (string, required): The ID of the strategy to clear

clear_everything

Clear all trees and strategies.

save_state

Manually save the current state to storage.

get_version

Get the version information of this ToT MCP server.

explore_with_strategy

Explore a thought tree using a systematic branching strategy.

Parameters:

  • treeId (string, required): The ID of the tree to explore

  • strategy (string, required): The branching strategy to use (bfs, dfs, beam, or best_first)

  • maxThoughts (number, optional): Maximum number of thoughts to explore (default: 100)

  • beamWidth (number, optional): Beam width for beam search strategy (default: 3)

  • stopCriteria (object, optional): Optional stop criteria

    • minEvaluation (number): Stop when a thought reaches this evaluation score

    • maxDepth (number): Stop when reaching this depth

    • targetThoughtCount (number): Stop when exploring this many thoughts

Returns:

  • thoughtsExplored: Number of thoughts explored

  • thoughtsCreated: Number of thoughts created during exploration

  • maxDepthReached: Maximum depth reached

  • bestThoughtId: ID of the best thought found

  • bestEvaluation: Evaluation score of the best thought

  • stoppedReason: Reason why exploration stopped

πŸ“– Usage Example

Here's a typical workflow for solving a problem using ToT:

  1. Create a tree with your goal and initial thought

  2. Add child thoughts representing different approaches

  3. Evaluate each thought based on its promise

  4. Select the best thoughts for further exploration

  5. Add more children to selected thoughts

  6. Backtrack if a path doesn't work out

  7. Prune low-scoring branches to focus resources

  8. Review the tree structure to understand the reasoning path

πŸ“Š Data Structures

Thought

{
  id: string;
  content: string;
  parentId: string | null;
  children: string[];
  evaluation: number | null;
  state: 'pending' | 'evaluated' | 'selected' | 'pruned';
  depth: number;
  createdAt: string;
  metadata?: Record<string, any>;
}

Tree

{
  id: string;
  rootId: string;
  thoughts: Map<string, Thought>;
  goal: string;
  createdAt: string;
  updatedAt: string;
  maxDepth: number;
  metadata?: Record<string, any>;
}

πŸ’Ύ Storage

Thought trees are persisted to tot-storage.json in JSON format. The storage mechanism uses:

  • Atomic Writes: Data is written to a temporary file first, then renamed to prevent corruption

  • Error Handling: Graceful recovery from corrupt files with detailed error messages

  • Schema Validation: Loaded data is validated to ensure structural integrity

  • Graceful Degradation: Corrupt or missing files result in an empty state rather than crashes

Logs of tool calls are stored in the output directory with daily rotation.

πŸ“„ License

MIT

Available Tools

38 tools
add_childB

Add a child thought to an existing thought

Inputs: treeId (required), content (required), parentId (required), metadata, +1 more.

backtrackA

Backtrack from a thought, marking all descendants as pruned

Inputs: treeId (required), thoughtId (required).

clear_everythingB

Clear all trees and strategies

Inputs: no named parameters.

clear_strategyB

Clear a specific strategy by ID

Inputs: strategyId (required).

clear_treeC

Clear a specific tree by ID

Inputs: treeId (required).

clone_tree_to_strategyA

Clone a tree into a strategy (deep copy with new IDs for tree and all thoughts)

Inputs: treeId (required), strategyIdOrName (required), namePrefix.

create_strategyA

Create a new Strategy for grouping related trees for long-term reasoning initiatives

Inputs: name (required), description.

create_treeB

Create a new Tree of Thoughts with a root thought and goal

Inputs: goal (required), rootContent (required), maxDepth, metadata, +1 more.

delete_session_treesA

Delete all trees and thoughts associated with a specific session ID for cleanup

Inputs: sessionId (required).

delete_treeB

Delete a tree by ID

Inputs: treeId (required).

evaluate_thoughtC

Evaluate a thought with a score (0-1 or 0-100) and optional multi-criteria fields

Inputs: score (required), treeId (required), thoughtId (required), risk, +3 more.

explore_with_strategyB

Explore a thought tree using a systematic branching strategy (BFS, DFS, beam search, or best-first search)

Inputs: treeId (required), strategy (required), beamWidth, maxThoughts, +1 more.

generate_and_evaluate_childrenB

Generate child thoughts and evaluate them in one call using LLM judge

Inputs: treeId (required), parentId (required), numChildren (required), metadata, +3 more.

generate_childrenC

Generate N diverse child thoughts for a parent thought (thought generation tool)

Inputs: treeId (required), parentId (required), numChildren (required), metadata, +1 more.

get_best_thoughtsB

Get the best evaluated thoughts in a tree, optionally sorted by criteria

Inputs: treeId (required), limit, sortBy.

get_session_contextA

Get all thoughts across all trees for a specific session ID to understand the full context

Inputs: sessionId (required).

get_strategyA

Get a strategy by ID or name (case-insensitive)

Inputs: id (required).

get_strategy_contextA

Get a strategy with its trees and basic statistics (aggregated view across trees in the strategy)

Inputs: strategyIdOrName (required).

get_thoughtC

Get a specific thought by ID

Inputs: treeId (required), thoughtId (required).

get_treeC

Get a tree by ID

Inputs: treeId (required).

get_tree_statsC

Get statistics about a tree

Inputs: treeId (required).

get_tree_structureB

Get the hierarchical structure of a tree

Inputs: treeId (required).

get_versionA

Get the version information of this ToT MCP server

Inputs: no named parameters.

list_strategiesA

List all strategies, optionally filtered by status

Inputs: status.

list_treesB

List all trees

Inputs: no named parameters.

list_trees_by_sessionA

List all trees associated with a specific session ID for context maintenance

Inputs: sessionId (required).

list_trees_by_strategyB

List all trees belonging to a strategy (by ID or name)

Inputs: strategyIdOrName (required).

move_subtreeA

Move a subtree to a new parent within the same tree. Performs cycle detection, depth validation, and supports dry-run mode for safe preview.

Inputs: treeId (required), newParentId (required), subtreeRootId (required), dryRun.

move_tree_to_strategyA

Move a tree to a strategy (lightweight operation that preserves original tree IDs)

Inputs: treeId (required), strategyIdOrName (required).

propose_and_evaluateB

Add a child thought and evaluate it in one call (auto-evaluation helper) with optional multi-criteria fields

Inputs: score (required), treeId (required), content (required), parentId (required), +5 more.

prune_treeC

Prune thoughts below a certain evaluation threshold, optionally by risk threshold

Inputs: treeId (required), threshold (required), riskThreshold.

refine_thoughtB

Refine a thought to better align with the goal using LLM

Inputs: treeId (required), thoughtId (required).

save_stateB

Manually save the current state to storage

Inputs: no named parameters.

select_thoughtA

Mark a thought as selected for further exploration (thought must be verified first)

Inputs: treeId (required), thoughtId (required).

self_reflect_thoughtB

Get a critique and improved version of a thought using LLM self-reflection

Inputs: treeId (required), thoughtId (required).

suggest_next_actionsA

Use this tool when you are unsure what to do next in the Tree of Thoughts process. It analyzes the current state of the tree (pending thoughts, low evaluations, high risk branches, depth progress, etc.) and returns prioritized, actionable recommendations such as: generate children, evaluate thoughts, prune low-value branches, verify good thoughts, backtrack, or use exploration strategies. Call this tool proactively when the tree feels stuck, has many pending items, or you need guidance on the best next step.

Inputs: treeId (required), focusThoughtId, maxSuggestions.

verify_thoughtA

Mark a thought as verified after confirming its findings. Required before a thought can be selected.

Inputs: treeId (required), thoughtId (required), verificationNotes.

visualize_treeB

Visualize a tree in human-readable format (ASCII, Mermaid, DOT, PNG, or SVG)

Inputs: treeId (required), format.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 38 tools

    Disambiguation4/5

    Most tools have clearly distinct roles across sessions, strategies, trees, and thoughts. However, clear_tree vs delete_tree and clear_strategy vs clear_everything have ambiguous boundaries that could cause an agent to pick the wrong cleanup operation.

    Naming Consistency5/5

    Tool names overwhelmingly follow a consistent verb_noun pattern like create_, get_, list_, delete_, and clear_. Minor deviations like backtrack and self_reflect_thought do not undermine the overall predictable structure.

    Tool Count2/5

    38 tools is excessive for a single MCP server and exceeds the 25+ threshold. Many operations could be consolidated, such as combining generation/evaluation helpers or reducing the number of clear/delete variants.

    Completeness4/5

    The core Tree of Thoughts workflow is well covered: tree creation, thought generation, evaluation, verification, selection, pruning, backtracking, exploration, and visualization. Notable gaps include no delete_strategy and no direct update_thought or update_tree operation, but these are workable limitations.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers