nornweave

NornWeave exposes an MCP server that lets AI agents connect directly to your inbox platform. The MCP interface provides a small set of tools that agents can invoke to manage inboxes and messages: creating new inbox addresses, sending emails (with automatic Markdown-to-HTML conversion), searching for relevant messages, and waiting for replies. To enable MCP access, run the CLI command nornweave mcp with the environment variable NORNWEAVE_API_URL pointing to the running API server (for example http://localhost:8000). Once the MCP server is up, you can configure your MCP client (such as Claude or Cursor) to point at the provided tool set and begin issuing the available tool calls.

The available tools include:

• create_inbox: Provisions a new virtual inbox address for an agent. Use it to allocate an inbox that the agent can operate on.
• send_email: Sends an email through your configured provider. The tool accepts content and automatically converts Markdown to HTML as needed.
• search_email: Finds messages within an inbox using search criteria to help agents locate relevant context.
• wait_for_reply: Blocks until a reply arrives to a thread (experimental, useful for agent workflows).

Configure the MCP client by pointing it at the nornweave MCP server and ensuring the API URL is reachable. The example configuration in the repository shows an MCP server named nornweave with command nornweave and argument mcp, along with the NORNWEAVE_API_URL environment variable. After configuration, agents can invoke the tools to manage inboxes and drive conversations end-to-end.

Prerequisites:

• Python 3.9+ (recommended) and a working Python environment
• Git installed on your system
• Network access to install Python packages from PyPI

Step-by-step installation:

1. Install Python and Git if not already present.
2. Create and activate a virtual environment (optional but recommended):
   • python -m venv venv
   • source venv/bin/activate (Linux/macOS) or venv\Scripts\activate (Windows)
3. Install the NornWeave package with MCP support:
   • pip install nornweave[mcp]
4. Start the MCP server via the CLI:
   • nornweave mcp
5. Ensure API is reachable
   • By default, the API runs at http://localhost:8000. If you use a different host/port, set NORNWEAVE_API_URL accordingly in your environment when running the MCP server.
6. (Optional) Run with Docker or other deployment methods if needed (see project docs for docker-compose setup and migrations).

Notes:

• If you are using a real email provider, you will need to configure a .env file with provider credentials and domain before starting the API.
• The MCP server relies on the main API being accessible at the URL configured via NORNWEAVE_API_URL.

Tips and caveats:

• Ensure NORNWEAVE_API_URL is reachable from the environment where the MCP server is running.
• For production, consider using a proper database (PostgreSQL) and run migrations as needed; SQLite is the default for local development.
• When using the MCP tools, remember that create_inbox and send_email will require proper provider configuration in the API (.env or environment variables).
• If you encounter connectivity or authentication issues with MCP clients, verify that the MCP endpoint is exposed and that the API URL in the MCP config matches the running API server.
• The wait_for_reply tool is experimental; use it in non-critical agent workflows until stable.
• Review the MCP integration docs in the repository for more advanced configurations and security considerations.