Risal Mcp Server

Control Risal — tasks, sprints, work timers, AI-cost tracking, and live server monitoring — straight from your AI agent, over the Model Context Protocol.

npm version npm downloads Docker Hub License: MIT Built for MCP

Risal is an AI-powered task & project management platform with built-in server monitoring. This MCP server exposes Risal's API as agent tools, so an LLM client (Claude Desktop, Claude Code, Cursor, or any MCP-capable agent) can:

• Plan & track work — create/update tasks, AI-parse a plan or notes into a task list, organize them into projects and sprints.
• Track time — start/stop the same cross-device work stopwatch the web app shows, or log minutes manually.
• Account for AI cost — log the agent's own model + token usage so it lands in Risal's cost report, and read that report back.
• Operate servers — read live CPU/RAM/disk metrics and alerts, and restart/start/stop Docker containers, systemd services and pm2 processes, fetch logs, run diagnostics, and manage down-alerts.

Everything is authed by a scoped personal access token and enforced server-side — a token can never manage your account, and only touches servers its owner enrolled.

Get an API key

In the Risal web app go to app.risal.io → Profile → API tokens, create a token, and pick the scopes you need:

Copy the token (risal_pat_…) — it's shown once. Scope it to the minimum your agent needs; you can revoke it anytime from the same screen.

Install

Both methods register the server with Claude Code under the name risal. Replace risal_pat_… with your token.

npx (recommended — only needs Node ≥ 18, nothing to build)

claude mcp add risal --scope user --env RISAL_API_KEY=risal_pat_… -- npx -y risal-mcp-server

Docker

claude mcp add risal --scope user --env RISAL_API_KEY=risal_pat_… -- docker run -i --rm -e RISAL_API_KEY shaxzod/risal-mcp-server:latest

{
  "mcpServers": {
    "risal": {
      "command": "npx",
      "args": ["-y", "risal-mcp-server"],
      "env": { "RISAL_API_KEY": "risal_pat_…" }
    }
  }
}

{
  "mcpServers": {
    "risal": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "RISAL_API_KEY=risal_pat_…", "shaxzod/risal-mcp-server:latest"]
    }
  }
}

Self-hosted Risal

Point the server at your own Risal API host with the RISAL_API_BASE env var (default https://api.risal.io). Add --env RISAL_API_BASE=https://api.your-risal.example to the claude mcp add command, or to the env block in the JSON.

Tools

Derived directly from the source — 42 tools across identity, tasks, and infra.

Identity

Tasks, projects & sprints

Work timers & time logging

AI usage & cost

Server monitoring (read)

Server management (write — async)

Server write actions are asynchronous. They queue a command the on-box Risal agent runs on its next heartbeat (~1 min). The tool returns a command id; call get_command to see its status (pending → done/failed), exit_code and output. Every action is tenant-scoped — a token can only touch servers its owner enrolled.

Usage examples

Natural-language prompts your agent can act on once the server is connected:

• "Turn these meeting notes into tasks for today and schedule the design ones for Thursday."
• "Start a timer on the 'fix auth bug' task." … later: "Stop the timer and mark it done."
• "Create a sprint for next week and move my three open backend tasks into it."
• "How much have I spent on AI for the risal-saas project this month?"
• "Which of my servers is highest on disk right now, and show its 7-day trend."
• "The nginx container on prod looks down — restart it and show me the last 50 log lines."
• "Log that I used claude-opus with ~12k prompt / 3k completion tokens on this task."

Develop / run from source

git clone https://github.com/ziyarago/risal-mcp-server.git && cd risal-mcp-server
npm install
npm run build          # tsc → dist/
RISAL_API_KEY=risal_pat_… npm start
# or hot-reload during development:
RISAL_API_KEY=risal_pat_… npm run dev

Publish (maintainers)

cd mcp-server
npm version patch                 # bump version
npm publish --access public       # prepublishOnly builds dist automatically

# Docker — tag the exact version and latest so users can pin or float:
VER=$(node -p "require('./package.json').version")
docker build -t shaxzod/risal-mcp-server:"$VER" -t shaxzod/risal-mcp-server:latest .
docker push shaxzod/risal-mcp-server:"$VER"
docker push shaxzod/risal-mcp-server:latest

CI (.github/workflows/ci.yml) type-checks and builds on every push/PR. Publishing is intentionally manual; an opt-in tag-triggered npm-publish job is included commented-out in the workflow.

Security

• The token is a Bearer credential — keep it in your MCP client's env, never in a prompt or committed file. Revoke it anytime in Profile → API tokens.
• All calls go to the Risal API over HTTPS; this server only proxies tool calls and stores nothing.
• Account management (sessions, deleting the account, minting tokens) is never reachable with a token, regardless of scope.

Links

• Risal — risal.io · app: app.risal.io
• npm — risal-mcp-server
• Docker Hub — shaxzod/risal-mcp-server
• Model Context Protocol — modelcontextprotocol.io

License

MIT © 2026 Ziyarago (Risal)