KunAvatar

KunAvatar is an MCP-enabled locally deployed AI assistant that uses Ollama as its inference engine and exposes MCP tooling for multi-model and multi-server orchestration. With KunAvatar, you can connect to one or more MCP-backed services, manage tools across servers, and enable real-time tool invocation through a unified interface. The server supports multiple transport mechanisms and integrates features like streaming responses (SSE/HTTP), task- and memory-aware agents, and RBAC-based access to tools. After starting the server, you can interact with the AI, choose from available Ollama models, manage agents (智能体), and call external tools via the MCP protocol to perform actions such as data retrieval, file operations, or external API calls. The MCP tooling layer also provides discovery, monitoring, and permission controls to fine-tune who can call which tools.

Prerequisites:

• Node.js 22.15+ and npm 11.3+ (as recommended by KunAvatar)
• Ollama installed and configured locally (available models pulled as needed)

Installation steps:

1. Clone the repository

git clone https://github.com/KunLabAI/kun-avatar.git
cd kun-avatar

2. Install dependencies

npm install

3. Build the project (if applicable)

npm run build

4. Start the MCP server (KunAvatar)

npm start

5. Optional: run in development mode

npx next dev

Notes:

• Ensure Ollama is running and accessible before starting KunAvatar.
• If you customize MCP tooling or add additional servers, update the mcp configuration accordingly.

Tips and common issues:

• Ensure Ollama is up-to-date (recommended >= 0.9.6+) and that the models you plan to use are pulled (e.g., ollama pull gemma3).
• The MCP tool layer supports multiple transport methods (stdio, SSE, Streamable HTTP). If you encounter connectivity issues, verify network/firewall settings and that the appropriate endpoints are accessible.
• For RBAC and multi-tenant setups, define roles and permissions carefully to prevent unauthorized tool usage.
• If you encounter port conflicts, adjust the Next.js API server port in the development or production configuration and re-run the server.
• When using the MCP API, you can leverage the auto-discovery feature to find available tools across servers and subscribe to tool status updates via SSE.