NotiCode

The blue, MCP-native AI agent for your whole machine.

Runs as an MCP server so Claude (or any MCP client) can plug in, chat, and let it edit files and drive your machine. DM it on Telegram. Or run everything at once and control one shared agent from your MCP client and your phone.

What is this?

NotiCode is an open AI agent in the spirit of OpenCode and Claude Code, with one twist: it speaks MCP first.

It has hands. It can read/write files, run shell commands, inspect your system, drive a headless browser, take screenshots and webcam photos, control your Home Assistant smart home, schedule recurring jobs, and message you on Telegram (text and photos). Connect it to an MCP client, talk to it in your terminal, or DM the Telegram bot, all backed by the same toolset.

It is blue. Not orange. On purpose.

Related MCP server: vulcan-file-ops

The one-command setup: all

node dist/index.js all
# or: npm run all

This boots everything in a single process:

• the HTTP MCP server (prints a URL you paste into any MCP client),

• the Telegram bot (DM it from your phone),

• the scheduler (cron jobs that notify you when done).

They all share the same tools and workspace. So you can text the bot "измени мои файлы" / "edit my files and run the tests", or type the same thing into an MCP client, and the same agent does the work on the same machine. Needs ANTHROPIC_API_KEY (for the bot) and TELEGRAM_BOT_TOKEN (to enable Telegram); the HTTP server and scheduler run even without them.

Do I need an API key?

• noticode mcp / noticode serve -- no key. NotiCode is just the hands; the MCP client you connect brings the brain.

• noticode chat / noticode telegram / noticode all -- needs ANTHROPIC_API_KEY, because here NotiCode calls the model itself.

Modes

Quick start

git clone https://github.com/Antropov31/noticode-mcp.git
cd noticode-mcp
npm install
npx playwright install chromium   # only if you want the browser_* tools
npm run build
cp .env.example .env               # fill in keys you want to use

Then pick a mode, e.g. the full stack:

npm run all

Connect Claude Desktop (stdio)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "noticode": {
      "command": "node",
      "args": ["/absolute/path/to/noticode-mcp/dist/index.js", "mcp"],
      "env": { "NOTICODE_WORKSPACE": "/absolute/path/to/your/project" }
    }
  }
}

Connect by URL (HTTP)

npm run serve (or all) prints something like http://127.0.0.1:4319/mcp. Paste it into any MCP client that supports the HTTP (Streamable HTTP) transport.

Telegram

1. Create a bot with @BotFather, put the token in TELEGRAM_BOT_TOKEN.

2. (Recommended) Get your chat ID from @userinfobot and set TELEGRAM_CHAT_ID to lock the bot to just you.

3. npm run telegram (or npm run all). Text the bot. /start and /reset are supported.

Tools

Image tools save a PNG and return its path; send it on with tg_send_photo. All tools are defined once in src/tools/ and shared by every mode.

Scheduler

schedule_add takes a cron expression and a job type:

• shell -- run a command; you get the output when it finishes.

• prompt -- run an agent instruction (only in all/chat with an API key).

• notify -- a plain reminder.

Results are pushed to you via Telegram when configured. Example: "every weekday at 9am, pull the repo and run tests" becomes a shell job on 0 9 * * 1-5.

Configuration

Security

NotiCode runs arbitrary commands, edits files, drives a browser, sees your screen and camera, and can control your home. That power is the point and the risk. Scope NOTICODE_WORKSPACE tightly, flip NOTICODE_ALLOW_SHELL / NOTICODE_ALLOW_WRITE to false when you only need read access, keep the HTTP bind on 127.0.0.1 and set NOTICODE_TOKEN before tunneling, and always set TELEGRAM_CHAT_ID so a stranger who finds your bot can't drive your machine.

When you bind HTTP beyond localhost, also set NOTICODE_ALLOWED_HOSTS (Host-header allowlist against DNS rebinding) and NOTICODE_ALLOWED_ORIGINS (which browser origins may connect). NOTICODE_MAX_SESSIONS / NOTICODE_SESSION_TTL_MS bound resource usage per session.

Trust model: sandboxed files, privileged shell

• fs_read / fs_write / fs_edit / fs_list / fs_search are sandboxed to NOTICODE_WORKSPACE (including symlink/junction escape checks). Paths outside the workspace are rejected with a Path must stay inside the workspace error — that rejection is the sandbox working, not a bug.

• shell_exec is deliberately privileged: it starts in the workspace but, like a normal user terminal, can cd anywhere and run anything (including absolute paths and git commands outside the workspace). Treat shell access as full local-user access and gate it with NOTICODE_ALLOW_SHELL=false when you need a locked-down agent.

Project structure

src/
  index.ts              CLI entry (all | mcp | serve | chat | telegram | help)
  config.ts             Env-based configuration
  theme.ts              Blue terminal palette + banner
  runner/
    all.ts              Unified mode: HTTP MCP + Telegram bot + scheduler
  mcp/
    server.ts           buildMcpServer + stdio entry point
    http.ts             Streamable HTTP entry point (prints a URL)
  agent/
    core.ts             Shared agent loop (model + tool-use)
    agent.ts            Interactive terminal chat
    telegram-bot.ts     Telegram bot bridge to the agent loop
  scheduler/
    scheduler.ts        Cron scheduler runtime
  tools/
    index.ts            Tool registry
    types.ts            Shared tool + context types
    filesystem.ts       fs_read / fs_write / fs_edit / fs_list / fs_search
    shell.ts            shell_exec
    system.ts           sys_info
    telegram.ts         tg_send / tg_send_photo / tg_read
    notify.ts           notify
    home-assistant.ts   ha_states / ha_call_service
    browser.ts          browser_navigate / click / type / eval / screenshot
    capture.ts          screen_capture / webcam_capture
    scheduler.ts        schedule_add / schedule_list / schedule_cancel

Roadmap

• HTTP / Streamable HTTP transport in addition to stdio

• Telegram bot bridge

• Unified all mode

• Browser automation, screen/webcam capture, Home Assistant, scheduler

• Streaming responses in chat mode

• Pluggable LLM providers (OpenAI, local models)

• Per-tool permission prompts

• Git-aware diffs before writes

License

MIT © Antropov31