How do I install the omnispindle mcp server?

Use a recorded configuration for your client, replace example credential values and paths, and verify the documented runtime. Restart or reconnect the client, then inspect the available tools.

What credentials does it need?

It reads `OMNISPINDLE_MODE`, `OMNISPINDLE_TOOL_LOADOUT`, `MCP_USER_EMAIL`, `MADNESS_AUTH_TOKEN`, `AUTH0_TOKEN`, `MADNESS_API_URL`, `MQTT_HOST` from the environment. Store these in your client's env block or a secrets manager — never commit them to a repository — and grant the narrowest scope that still covers your use case.

SSyncDev

Start a project

Omnispindle MCP Server

Omnispindle is the coordination spine of the Madness Interactive ecosystem — a Python FastMCP server with 38 tools that lets AI agents manage tasks

Local serverstdioPython

What is the Omnispindle MCP Server?

Omnispindle is the coordination spine of the Madness Interactive ecosystem — a Python FastMCP server with 38 tools that lets AI agents manage tasks, capture knowledge, coordinate sessions, track epic goals (quests), and navigate the whole workshop from a single, standardized interface. PyPI.

What Omnispindle does

Practical notes

Maintained by MadnessEngineering, written in Python.

More MCP options

Compare MCP servers by category, or browse hosted MCP servers if you prefer an endpoint over a local process.

Maintainer setup documentation.

Recorded tools

Check the linked publisher documentation and your connected client's tool list. Names and availability can vary with the server version and account permissions.

Tool	What it does
add_todo	Create a task with project, priority, target agent, notes, and metadata
query_todos	MongoDB-style filter queries with projection, limit, offset, since change detection, and graph_root for dependency subgraph traversal
update_todo	Patch any fields; metadata is deep-merged. Supports $push/$pull on array fields (e.g. metadata.blockers) for dependency linking
delete_todo	Remove a task
get_todo	Fetch a single task by ID
complete_todo	Stage for review with optional comment; writes to audit log. Sets status to review, not completed
list_todos_by_status	Filter by status: pending initial in_progress blocked review completed
search_todos	Tokenized multi-word fuzzy text search
list_project_todos	Recent tasks for a specific project
add_lesson	Capture a lesson with language, topic, and tags
get_lesson	Fetch by ID
update_lesson	Patch lesson content or metadata
delete_lesson	Remove
search_lessons	Text search across lesson fields
grep_lessons	Regex pattern search
list_lessons	Browse all lessons, with brief mode for summaries
inventorium_sessions_list	List sessions, optionally filtered by project
inventorium_sessions_get	Fetch a session by ID
inventorium_sessions_create	Start a new AI work session
inventorium_sessions_spawn	Spawn a child session from a parent, linked to a todo
inventorium_sessions_fork	Fork a session with optional message inheritance
inventorium_sessions_genealogy	Full ancestor/descendant trace for a session
inventorium_sessions_tree	Visual session tree for a project
inventorium_todos_link_session	Link a todo to a session
create_quest	Create an epic goal container (Quest → Chains → Todos). Use instead of add_todo for multi-step objectives
check_quest	Progress report: % complete, per-chain status, next actions, blockers. Agent orientation tool
list_quests	List quests filtered by status/project
link_quest	Add an existing todo to a quest chain retroactively (creates chain on demand)
update_quest	Update quest fields: name, description, status, success_criteria, metadata
get_context_bundle	One call: recent todos, lessons, session state, project stats for an agent's working context
find_relevant	Semantic similarity search across todos and lessons. Returns honest empty when nothing clears the relevance threshold — no regex fallback noise
preflight_rag	Pre-task lessons check: call before starting work, classifies past solutions vs pitfalls
query_todo_logs	Audit log queries: filter by type, project, date range
list_projects	Enumerate known projects from filesystem
point_out_obvious	Logs an observation with configurable sarcasm. Useful for marking known issues during automated runs.
bring_your_own	Inject a Python, JavaScript, or shell function as a live MCP tool at runtime
Loadout	Tools
full	38
basic	15
minimal	4
lessons	8
admin	16
write_only	6
read_only	16
lightweight	13
agent_preflight	6
refine	13

How to install the Omnispindle MCP Server

{
  "mcpServers": {
    "omnispindle": {
      "command": "omnispindle-stdio",
      "env": {
        "OMNISPINDLE_MODE": "api",
        "OMNISPINDLE_TOOL_LOADOUT": "basic",
        "MCP_USER_EMAIL": "you@example.com"
      }
    }
  }
}

From the project documentation. Replace placeholders and example paths before connecting.

Configuration

Variable	Description	Required
OMNISPINDLE_MODE	Declared in the maintainer’s client configuration.	Check documentation
OMNISPINDLE_TOOL_LOADOUT	Declared in the maintainer’s client configuration.	Check documentation
MCP_USER_EMAIL	Declared in the maintainer’s client configuration.	Yes

Example prompts to try

“Use Omnispindle to add todo.”
“Use Omnispindle to query todos.”
“Use Omnispindle to update todo.”

Frequently asked questions

Omnispindle is the coordination spine of the Madness Interactive ecosystem — a Python FastMCP server with 38 tools that lets AI agents manage tasks, capture Confirm the tools offered by your installed version in the connected client. Tool availability and permissions depend on the server and account configuration.