Based on repository activity, growth velocity and community engagement.
30
Growth5/30
Activity7/25
Popularity12/25
Trust7/20
842
Stars
High
Sentiment
Votes
842
README.md
Nanobot - Build MCP Agents
Warning
This project is under heavy development and is moving away from its original design and intent. Expect significant breaking changes, architectural shifts, and evolving APIs.
Nanobot enables building agents with MCP and MCP-UI by providing a flexible MCP host.
While existing applications like VSCode, Claude, Cursor, ChatGPT, and Goose all include an MCP host,
Nanobot is designed to be a standalone, open-source MCP host that can be easily deployed or integrated into
your applications. You can use Nanobot to create your own dedicated MCP and MCP-UI powered chatbot.
What is an MCP Host?
An MCP host is
the service that combines MCP servers with an LLM and context to present an agent experience to a
consumer. The primary experience today is a chat interface, but it can be many other interfaces such
as voice, SMS, e-mail, AR/VR, Slack, MCP, or any other interface that can be used to interact with
an agent.
You can organize your configuration as a directory with a top-level nanobot.yaml for shared settings and individual .md files for each agent.
Directory Structure:
my-config/
├── nanobot.yaml # Shared config: mcpServers, llmProviders, env, etc.
└── agents/ # Agent definitions directory
├── main.md # Main agent (auto-set as entrypoint)
└── helper.md # Additional agent
LLM Providers
openai and anthropic are built-in providers — set OPENAI_API_KEY or ANTHROPIC_API_KEY and they work with no additional config. Use the {provider}/{model} format in the model field to select a provider.
Additional providers (Azure, Bedrock, Ollama, etc.) can be configured in nanobot.yaml under llmProviders.
Each entry specifies a dialect (the API protocol), credentials, and base URL. The dialect field accepts:
---
name: Shopping Assistant
model: anthropic/claude-3-7-sonnet-latest
mcpServers:
- store
temperature: 0.7
---
You are a helpful shopping assistant.
Help users find products and answer their questions.
The YAML front-matter supports all agent configuration fields (model, name, mcpServers, tools, temperature, etc.), and the markdown body becomes the agent's instructions. Markdown agents take precedence over any agents defined in nanobot.yaml with the same name.
Usage:
nanobot run ./my-config/
The default config path is .nanobot/, so nanobot run with no arguments will use that directory if it exists.
Features:
Agent directory: All agent .md files must be in the agents/ subdirectory
Auto-entrypoint: If agents/main.md exists, it's automatically set as the default agent
Markdown precedence: Agents defined in agents/*.md override same-named agents in nanobot.yaml
README.md: Automatically ignored in the agents/ directory (use it for documentation)
Deprecated:mcp-servers.yaml and mcp-servers.json are still supported for backwards compatibility but are deprecated. Define mcpServers in nanobot.yaml instead.
