mcp server

nekoclaw-new

ReAct Agent Project — an LLM framework that alternates reasoning with tool use: think, act, observe, adapt. Better reliability for multi-step tasks compared to one-shot generation.

junglingtao/nekoclaw_newcommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

This project does not publish an install method we can turn into a config. Follow the README instead.

README

synced Oct 22, 2026

NekoClaw 🐈

A lightweight personal AI Agent framework with Web UI, multi-IM channel support, file system projects, Skills/MCP tools, cron jobs, and heartbeat.

NekoChat: a Cursor/Trae-like Web UI with file explorer, code editor, and chat — all in one interface.

Features

🖥️ NekoChat Web UI — Cursor-style interface with sidebar file tree, code editor, and chat pane
📁 Open Folder — register any folder as a project, browse files, edit code inline
🔧 Skills system — extensible with built-in skills (memory, cron, github, tmux)
🛠️ MCP tools — Model Context Protocol support for custom tools
📱 Multi-channel — Web UI + Telegram + QQ bot support
⏰ Cron jobs — schedule recurring tasks via the agent
💓 Heartbeat — periodic autonomous background tasks
🎨 Dark/Light theme — follows system preference with manual toggle

Quick Start

Prerequisites

Python 3.11+
Node.js 18+ (for building the frontend)

Installation

# Clone the repository
git clone https://github.com/YOUR_USERNAME/nekoclaw.git
cd nekoclaw

# Install Python dependencies
pip install -e .

# Build the frontend
cd nekochat/nekochat_frontend
npm install
npm run build
cd ../..

# Start NekoClaw
python -m nekoclaw

On first launch, you'll be prompted to configure:

API base URL (e.g., https://api.openai.com/v1 for OpenAI, https://api.moonshot.cn/v1 for Kimi)
API key (your LLM provider's API key)
Model (e.g., gpt-5.5, kimi-k2.6, deepseek-v4-pro)

Configuration

All settings are stored in ~/.nekoclaw/:

File	Purpose
`~/.nekoclaw/providers.json`	API key, base URL, model
`~/.nekoclaw/channels.json`	Channel settings (NekoChat, Telegram, QQ)
`~/.nekoclaw/runtime.json`	Agent behavior, temperature, max tokens

Edit these files directly or use the NekoChat UI Configuration panel.

Open in Browser

After starting, open http://127.0.0.1:8899 in your browser.

Supported API Providers

NekoClaw works with any OpenAI-compatible API:

Provider	Base URL	Notes
OpenAI	`https://api.openai.com/v1`	Full support, including o-series reasoning
Kimi (Moonshot)	`https://api.moonshot.cn/v1`	Auto-detected — thinking mode handled automatically
DeepSeek	`https://api.deepseek.com`	Auto-detected — thinking mode handled automatically
OpenRouter	`https://openrouter.ai/api/v1`	Multi-model gateway
Custom	Any OpenAI-compatible endpoint	Reasoning effort auto-detected

Architecture

nekoclaw/
├── agent/          # ReAct loop, dispatcher, subagent, memory, skills
│   └── tools/      # Built-in tools: shell, filesystem, web, message, etc.
├── providers/      # LLM provider layer (OpenAI-compatible)
├── bus/            # In-process message bus
├── channels/       # IM/Web adapters: nekochat, telegram, qq
├── skills/         # Internal + optional skill packages
├── session/        # Conversation session persistence
├── cron/           # Scheduled task service
├── heartbeat/      # Periodic heartbeat service
├── config/         # Configuration schema, loader, runtime paths
├── projects/       # "Open Folder" project layer (file tree, search, bind)
├── startup/        # Bootstrap: logging, config, venv, browser
├── templates/      # Workspace templates (en/cn)
├── lightsear/      # Web search/scrape library (Playwright-based)
├── nekochat/       # Vue 3 + TypeScript frontend
└── tests/          # Test suite

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/

# Frontend dev server (hot reload)
cd nekochat/nekochat_frontend
npm run dev

License

MIT License — see LICENSE file for details.