Odin MCP server
Commit Nov 10, 2026A self-hosted execution agent for Discord that runs shell commands, manages files, automates browsers, and orchestrates sub-agents on managed hosts.
Also known as Calmingstorm/Odin
- Stars
- 3
- Tools
- 6
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 10, 2026
- License
- MIT
What is Odin MCP?
Odin is a self-hosted execution agent for Discord that runs shell commands, manages files, automates browsers, and orchestrates sub-agents on managed hosts. It exposes 6 tools, such as discord, tools, permissions.
Summary generated from the project's README
About Odin MCP server
Odin provides a self-hosted execution environment for infrastructure operators who want to manage systems through Discord or a desktop application. Instead of just describing actions, it executes shell commands, manages files, and performs browser automation using Playwright. It is designed for users running real infrastructure who require bounded autonomy through permission tiers, command governors, and strict iteration limits.
Users can deploy Odin on Debian or Ubuntu systems to manage local or remote hosts via SSH. The system supports multiple model providers including OpenAI Codex, Ollama, and OpenAI-compatible endpoints like DeepSeek. It features a comprehensive WebUI for monitoring live executions, managing sub-agents, and reviewing audit logs with optional HMAC tamper evidence. For those preferring a local setup without a Discord account, Odin Desktop offers the same engine for Linux, Windows, and macOS.
What you can do with it
- 1Automated Infrastructure TroubleshootingAn operator can ask the agent to investigate a service failure and apply a fix to a staging environment.
- 2Browser-Based Task AutomationDevelopers can use the agent to perform web tasks such as form entry or data extraction from rendered pages.
- 3Orchestrating Parallel WorkflowsYou can delegate complex tasks to multiple isolated sub-agents to handle parallel or nested operations.
- 4Scheduled System MaintenanceUsers can set up recurring jobs or webhook-triggered workflows to maintain their managed hosts.
Written from the project's README. Every use case is checked against a quote from it.
Odin MCP tools 6
Detected from the READMEdiscordtoolspermissionsagentsno-newconfiguration
| discord | — | |
| tools | — | |
| permissions | — | |
| agents | — | |
| no-new | — | |
| configuration | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecalmingstorm/odin is public and reachablegithub.com/calmingstorm/odin ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/calmingstorm/odin ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubOdin is a self-hosted execution agent for Discord. Ask it to do something in a channel and it does the work: shell commands on the hosts you registered, repository changes, service operations, browser sessions, scheduled jobs, or a fan-out of sub-agents — then reports what actually happened, with an audit record of every tool call it made.
It is built for people who run real infrastructure and want an agent that executes rather than describes, inside limits they set: per-user host access, permission tiers, a command governor, secret redaction, and an audit log with optional HMAC tamper evidence.
| Built-in tools | shell and SSH, files and patches, background processes, browser automation, web, scheduling, sub-agents, knowledge base, and memory |
| Model providers | OpenAI Codex over a ChatGPT subscription, OpenAI-compatible endpoints (including Kimi and compatible hosted or self-hosted services), or Ollama — switch at runtime |
| Management WebUI | live execution viewer, agents, loops, processes, schedules, audit, sessions, usage, tools, skills, knowledge, hosts, config, and turn state; routes and tools are defined by the shipped registries |
| Bounded autonomy | iteration, lifetime, and nesting limits; durable turn state that survives model-capacity outages without replaying side effects |
| Tested | Regression tests exercise the shipped tool catalog, API routes, and tool loop |
Odin Desktop
Prefer an app to a Discord bot? Odin Desktop is Odin as a desktop app for Linux, Windows 11 and macOS (Apple silicon): the same engine and tools, running on your own computer, with no server or Discord account. It can import your memory, skills, MCP servers and hosts from an existing Odin. Download Odin Desktop.
What it looks like
An illustrative exchange — the hostnames are invented, the behaviour is what Odin does.
operator: the staging API is returning 502s since the deploy — find out why and fix it if it's safe
Odin: Probed
https://staging.example.internal/health→ 502 in 40 ms, upstream refused.systemctl status api-stagingshows the unit flapping since 14:02; the journal ends inaddress already in use :8080— the previous worker was never reaped. Killed the orphan (PID 41822), restarted the unit, health is 200 in 12 ms across five probes. Validation bundle passed 4/4 (service active, port open, HTTP 200, no new errors in 60 s). Audit record#8813.
The WebUI shows every tool Odin can reach, how often each has run, and lets you switch any built-in tool off for the model:
Quick start
Security warning: configure API authentication before starting or exposing Odin. With no API token configured (empty
web.api_token, noweb.api_tokensentries, and no managed tokens), the general API authentication gate is disabled: API routes relying on that gate are unauthenticated. Set a strong, privateweb.api_tokento secure the installation, and restrictweb.hostto loopback unless deliberately exposing it behind TLS and access controls. This matters especially when enabling desktop observation and stored evidence. Computer routes additionally require an authenticated admin identity; their separate checks do not secure the rest of a tokenless installation.
Debian or Ubuntu. APT resolves dependencies and the package installs Python extras during setup, which can take a few minutes. Optional computer-use support has distribution-specific requirements; see the packaging handoff.
curl -LO https://github.com/Calmingstorm/Odin/releases/latest/download/odin_4.29.0_amd64.deb
sudo apt install ./odin_4.29.0_amd64.deb
# then open http://127.0.0.1:3000/ui/ and follow the guided setup
A fresh install enables and starts a restricted loopback bootstrap service, and the guided setup creates your admin token and takes the Discord token and the provider device authorization. Open http://127.0.0.1:3000/ui/ locally. For a remote install, run ssh -L 3000:127.0.0.1:3000 user@odin-host on your workstation, then open that same local URL. Do not publish pending setup through a reverse proxy.
On the setup page, select Generate admin token, copy the token somewhere safe and save setup, then sign in with it as administrator. You sign in with that token from now on. System → Config → Web listener exposure shows the configured host, whether it came from an explicit web.host key or the schema default, and the addresses the current process actually owns. Authorize beyond-loopback access there and re-enter a current admin API token. This records permission for the next start, not a live rebind. After arranging TLS and network access controls, restart manually with sudo systemctl restart odin. The same card can revoke authorization and narrow the next start to loopback. A Discord token alone never authenticates or widens the Web listener.
Prefer the shell to the guided setup? The same steps by hand:
sudoedit /etc/odin/.env # DISCORD_TOKEN=...
sudo -u odin /opt/odin/.venv/bin/python /opt/odin/scripts/codex_login.py \
--credentials-path /var/lib/odin/codex_auth.json --device
sudoedit /etc/odin/config.yml # set web.api_token; bind web.host to 127.0.0.1 unless it sits behind TLS;
# review permissions.default_tier (template: admin) and tools.hosts
sudo systemctl restart odin # WebUI on the configured web.port (default 3000)
The package also grants the odin service account passwordless sudo; restrict /etc/sudoers.d/99-odin-passwordless before the service is reachable from anywhere you do not control. Then invite the bot, register the hosts it may reach in System → Hosts, and ask it for something harmless first. The full walkthrough, including a source checkout for development, is under Installation.
Capabilities
Systems and software operations
- Run commands and scripts on local or remote managed hosts over SSH.
- Read and write files, manage long-running processes, and transfer generated artifacts.
- Work with Git repositories, Docker, Kubernetes, and Terraform.
- Probe HTTP endpoints and run post-change checks against services, ports, processes, logs, commands, and URLs.
- Use Playwright for rendered page inspection, screenshots, table extraction, form entry, clicks, and JavaScript evaluation.
Automation
- Run recurring cron schedules, one-time jobs, and webhook-triggered workflows.
- Delegate sequential background workflows with conditional steps.
- Run autonomous monitoring loops with explicit iteration and stop limits.
- Spawn isolated sub-agents for parallel or nested work and collect their results into the parent task.
- Preserve turn state across model-capacity interruptions without automatically repeating interrupted side effects.
State and retrieval
- Persist channel sessions and compact long conversations against configurable context budgets.
- Store operator-approved personal or global memory notes.
- Search conversation history and the tool audit log.
- Ingest and search a knowledge base using full-text and vector retrieval.
- Record per-turn trajectories, tool use, timing, and model usage.
Extensibility
- Create, edit, enable, disable, import, export, and invoke Python skills at runtime.
- Configure skills with JSON schemas, dependencies, and operator-managed settings.
- Integrate external systems through webhooks, email, MCP servers, and custom skill code.
Management interface
The web interface provides grouped views for:
- chat and current system posture;
- active execution, agents, loops, processes, and schedules;
- audit records, sessions, traces, and model usage;
- tools, skills, knowledge, memory, and learned context (automatic learning is opt-in; administrators can switch it live under Capabilities → Learned without affecting deliberate memory);
- health, resources, logs, configuration, permissions, host access, and updates.
The API exposes REST routes plus health, webhook, WebSocket, and static-interface routes. The authoritative route characterization test and generated API reference track the shipped inventory. The static built-in tool catalog is distinct from dynamically configured tools, including computer-use tools. Packaged computer-use operator handoffs are listed in packaging/nfpm.yml.
Execution model
flowchart TD
A["Discord · Web API · CLI"] --> B["Request admission & identity<br/>channel / user / mention / bot / permission policy"]
B --> C["Context assembly<br/>session history · context files · memory · tools for this requester"]
C --> D["LLM provider<br/>Codex · OpenAI-compatible endpoints · Ollama"]
D --> E{"Tool loop"}
E -->|built-in tools| F["Managed hosts & services<br/>shell · SSH · files · processes · browser · web"]
E -->|native handlers| G["Discord, agents, schedules, loops"]
E -->|skills & MCP| H["Runtime skills · configured MCP servers"]
F --> E
G --> E
H --> E
E --> I["Validation · audit · trajectory · result delivery"]
For a normal Discord request:
- The intake pipeline applies channel, user, mention, bot, and permission policy.
- Odin assembles session history, configured context, and the tools available to that requester.
- The active provider returns text, tool calls, or both.
- The tool loop validates and dispatches calls until the request completes or an iteration, time, or cancellation limit is reached.
- Tool results are recorded and returned to the model for the next step.
- After a recognized mutation, the tool loop asks the model to run
validate_actionbefore the final response, retrying the request a bounded number of times; it does not hold finalization indefinitely. - The final response and turn trajectory are persisted and delivered to Discord or the API caller.
Odin supports Codex, OpenAI-compatible providers, and Ollama:
| Provider | Authentication | Notes |
|---|---|---|
| OpenAI Codex | OAuth device or browser flow | Primary provider path; supports account rotation and separate spawned-agent model settings |
| OpenAI-compatible endpoints | Provider-specific credentials | Presets include hosted providers such as DeepSeek and OpenRouter; compatible local endpoints include vLLM, llama.cpp, and LM Studio. See compatible-provider configuration. Kimi is also available through this compatible lane. |
| Ollama | Local or remote endpoint; optional bearer token | Self-hosted provider path |
The provider can be changed through configuration or the web interface. The Codex Advanced panel uses an explicit save action. Codex connection-pool and context-compression changes are saved immediately but require an Odin restart. Provider support does not imply that every model has equivalent tool-calling behavior or context limits.
Built-in tools
The current release's static built-in tool registry is assembled from ordered definition modules under src/tools/defs/; characterization tests pin the catalog order and prevent duplicate names. Runtime visibility can additionally include configured dynamic tools.
| Area | Tools |
|---|---|
| Shell and files | run_command, run_script, run_command_multi, read_file, apply_patch, generate_file, post_file, manage_process |
| Infrastructure | http_probe, validate_action |
| Scheduling and workflows | schedule_task, schedule management, delegated tasks, autonomous loops |
| Agents | spawn, message, inspect, wait for, collect, and terminate agents |
| Browser and web | web search and fetch, screenshots, rendered page and table reads, clicks, form entry, JavaScript evaluation |
| Knowledge and state | history and audit search, knowledge ingestion and retrieval, memory, lists |
| Skills | create, edit, invoke, import, export, inspect, enable, disable, and delete skills |
| Communication and media | Discord operations, email, PDF and image analysis, image generation |
The complete catalog is defined in src/tools/registry.py and src/tools/defs/, and rendered with every parameter in the tool reference on the developer hub, alongside the REST API reference and an architecture guide.
Safety and access control
Odin can change real systems. It should be deployed as an administrative service and configured accordingly.
The implementation includes the following controls:
- Permission tiers:
admin,user, andguest. Theusertier excludes arbitrary shell execution and administrative tools, but its allowlist includes limited stateful operations such as list management. The tracked deployment template sets the effective default tier toadmin; operators should change it if that is not appropriate for their server. - Host access policy: per-user host allowlists and default-host selection, with request-scoped restrictions for API callers.
- CommandGovernor: classifies shell commands before execution. Depending on configuration and caller tier, it can reject critical or exfiltration patterns, annotate high-risk commands, or allow an administrator override. The tracked template enables administrator override.
- Workspace isolation: local commands run from a dedicated private workspace outside the application and data directories. Local command execution fails closed if that workspace is missing, incorrectly owned, or not mode
0700. - Secret handling: model input, tool output, attachments, and stored records pass through secret-detection and redaction paths.
- Network request guards: browser automation and general web-fetch paths validate destinations and redirect hops to reduce SSRF and DNS-rebinding risk. Individual integration tools may apply narrower policies appropriate to their purpose.
- Audit logging: tool calls are written to append-only JSONL records. Optional HMAC chaining provides tamper evidence, and rotation limits unbounded growth.
- Post-change validation: recognized mutations are flagged for follow-up validation; the tool loop requests it with bounded retries before finalizing.
- Web authentication: bearer-token and session authentication are available for the management API and interface.
These are application controls, not a security boundary equivalent to a virtual machine. Skills execute in the Odin process as trusted plugins. The Debian installer also grants the odin service account passwordless sudo by default because host administration is a primary use case; production operators should restrict /etc/sudoers.d/99-odin-passwordless to the commands their deployment needs.
The tracked configuration binds the web server to 0.0.0.0 and leaves API authentication disabled when no API token is configured. Before exposing it beyond a controlled network, configure an API token or token identity, transport security, and appropriate network controls.
See docs/security.md for the detailed security model.
Selected operational record
The following examples are drawn from completed operator sessions and repository records. They describe work performed through Odin rather than synthetic capability claims.
- Repository integration and concurrency safety: Calmingstorm/wanderer#2, merged on 2026-08-01, rebased a maintained fork onto upstream and added guarded signature imports, reconciliation previews, transactional updates, and serialization around concurrent graph mutations.
- Security review and remediation: during review of a payout-transfer change, Odin identified an unauthenticated execution route, moved execution behind the administrative API and authenticated actor context, updated the API smoke test, reran the project checks, and merged the corrected change.
- Minecraft release operations: Odin has prepared and published versioned modpack artifacts, updated AMP-managed servers while preserving worlds and local files, and validated application state, listening ports, mod loading, KubeJS checks, and server tick rate after restart.
- Infrastructure recovery: Odin traced loss of apparent audit history to rotation and restart behavior, hardened a backup guard to treat active and rotated audit segments as one store, added JSON and high-water validation, and completed a subsequent Restic backup with the protected data included.
- Runtime extension: deployment-specific skills extend Odin for the services an operator actually runs — game-server panels, DNS and cloud providers, release publishing, hardware status — and enforce their own confirmation and validation requirements on top of the built-in tool controls.
Operational results depend on credentials, host access, third-party availability, project state, and the quality of the selected model. Odin records tool outcomes so an operator can distinguish completed work from attempted or interrupted work.
Installation
Debian or Ubuntu package
Releases include an amd64 .deb package. Download the current package from the releases page, then install it with APT:
sudo apt install ./odin_*_amd64.deb
The package installs:
| Purpose | Path |
|---|---|
| Application | /opt/odin |
| Configuration | /etc/odin/config.yml |
| Environment file | /etc/odin/.env |
| Persistent data | /var/lib/odin |
| Local command workspace | /var/lib/odin-workspace |
| Logs | systemd journal (sudo journalctl -u odin); /var/log/odin is created but not written |
| Systemd unit | /usr/lib/systemd/system/odin.service |
| Private computer evidence (service-owned, 0700) | /var/lib/odin/computer |
| Precompiled root-owned Wayland guardian | /usr/libexec/odin-computer-wayland-input |
| Inert GNOME scope extension (not enabled) | /usr/share/gnome-shell/extensions/odin-scope@calmingstorm.net/ |
| Computer-use installation handoff | /usr/share/doc/odin/computer-use/PACKAGING.md |
| Computer-use setup and recovery | /usr/share/doc/odin/computer-use/OPERATOR.md, RECOVERY.md |
The package installs the application files and systemd unit. Its post-install script creates the odin service account, virtual environment, SSH key, data directories, configuration links, and local command workspace. Since v4.0.0, a fresh installation is enabled and started in loopback-only bootstrap mode; v3.98.0 and earlier packages were enabled but required manual configuration and start. See the Quick start for local access and SSH forwarding. Upgrades preserve configuration and data and restart the service only if it was already running.
Fresh installs and upgrades install the pdf and computer Python extras and
provision private computer state with symlink rejection. Computer enablement is
preserved on upgrade; installing the package does not authorize a computer task.
Base dependencies are Python/venv, SSH, systemd and sudo. Computer OS tools,
libraries and applications are APT Recommends; headless operators can install
with sudo apt install --no-install-recommends ./odin_VERSION_amd64.deb.
Direct dpkg -i does not resolve dependencies, so APT is recommended.
Compositor/portal packages are Suggests, never an implicit new desktop.
Desktop target configuration, grants, Wayland UID/session bus, GNOME extension
activation and portal consent remain explicit operator choices. Historical Wayland
qualification used specific Debian 13 GNOME fixtures, not every desktop or app.
Stock Ubuntu 24.04's older libei does not meet the
guardian's libei >= 1.3.901 requirement; this is a dependency limitation, not a
compositor diagnosis. Missing Xed on a distribution does not block isolated
Drawing: common dependencies are checked at Enable, the selected app at start.
See PACKAGING.md for source versus package setup
and exact evidence limits. R9 exercised local package install/upgrade in disposable
containers, not a release pipeline or zero-click desktop setup.
For supervised use on your own screen, start with the
operator guide and
recovery guide. The R11 general attached-app/action
and compositor expansion is an implementation contract pending its own validation,
not a new qualification claim. The operator handoffs listed in packaging/nfpm.yml ship in the package;
engineering history stays in the repository. Remote worker transport is assessment
only and is not implemented.
First-time setup
Before starting the service: follow the Quick start security warning.
Set web.api_token and review the listening address before exposing the WebUI/API,
including installations intended for desktop observation and evidence access.
- Create a Discord application and bot in the Discord developer portal. Enable Message Content Intent.
- Set the Discord token:
sudoedit /etc/odin/.env
# DISCORD_TOKEN=...
- Authenticate Codex, or configure Kimi or Ollama later through the web interface:
sudo -u odin /opt/odin/.venv/bin/python \
/opt/odin/scripts/codex_login.py \
--credentials-path /var/lib/odin/codex_auth.json \
--device
- Review hosts, permissions, the command workspace, and the web API token:
sudoedit /etc/odin/config.yml
- Start the service and inspect startup:
sudo systemctl restart odin
sudo systemctl status odin
sudo journalctl -u odin -f
The web interface listens on the configured web.port, which defaults to 3000.
From source
Python 3.11 or newer is required. CI currently runs on Python 3.12.
git clone https://github.com/Calmingstorm/Odin.git
cd Odin
python3 -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
# Optional browser support
pip install -e ".[browser]"
python -m playwright install chromium
cp .env.example .env
# Set DISCORD_TOKEN in .env and review config.yml.
Odin MCP questions
What tools does Odin MCP provide?
It exposes 6 tools, including discord, tools, permissions, agents, no-new.
What can Odin execute?
Odin can run shell commands and scripts via SSH, manage files and patches, automate browsers with Playwright, and handle background processes or scheduled jobs.
How does Odin handle security and permissions?
Odin provides bounded autonomy through per-user host access, permission tiers, a command governor, and an audit log with optional HMAC tamper evidence.