{"id":"d5e550c4-7c77-44c9-8f6b-5beb47e994b8","slug":"nornweave","kind":"mcp","name":"nornweave","summary":"An open-source, self-hosted API that turns standard email providers (Mailgun, SES, SendGrid) into \"Inbox-as-a-Service\" for AI Agents.","owner":"DataCovey","repoUrl":"https://github.com/DataCovey/nornweave","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":29,"match":null,"fewStars":false,"format":"mcp","createdAt":null,"addedAt":"2026-10-14T05:02:39.492Z","logoUrl":"https://avatars.githubusercontent.com/u/258330720?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["productivity","cloud-infra"],"tags":["agent","email","llm","ai-tools","llm-agents","python","self-hosted"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T05:04:36.626Z","sample":false,"url":"https://conduits.dev/tools/nornweave","language":"Python","transports":["stdio"],"install":{"pypi":"nornweave"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<p align=\"center\">\n  <img src=\"web/static/images/Nornorna_spinner.jpg\" alt=\"The Norns weaving fate at Yggdrasil\" width=\"400\">\n</p>\n\n<h1 align=\"center\">NornWeave</h1>\n\n<p align=\"center\">\n  <em>\"Laws they made there, and life allotted / To the sons of men, and set their fates.\"</em><br>\n  - Voluspa (The Prophecy of the Seeress), Poetic Edda, Stanza 20\n</p>\n\n<p align=\"center\">\n  <strong>Open-source, self-hosted Inbox-as-a-Service API for AI Agents</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/DataCovey/nornweave/actions\"><img src=\"https://github.com/DataCovey/nornweave/workflows/CI/badge.svg\" alt=\"CI Status\"></a>\n  <a href=\"https://github.com/DataCovey/nornweave/blob/main/LICENSE\"><img src=\"https://img.shields.io/badge/license-Apache--2.0-blue.svg\" alt=\"License\"></a>\n</p>\n\n---\n\n## What is NornWeave?\n\nStandard email APIs are stateless and built for transactional sending. **NornWeave** adds a **stateful layer** (Inboxes, Threads, History) and an **intelligent layer** (Markdown parsing, Semantic Search) to make email consumable by LLMs via REST or MCP.\n\nIn Norse mythology, the Norns (Urdr, Verdandi, and Skuld) dwell at the base of Yggdrasil, the World Tree. They weave the tapestry of fate for all beings. Similarly, NornWeave:\n\n- Takes raw \"water\" (incoming email data streams)\n- Weaves disconnected messages into coherent **Threads** (the Tapestry)\n- Nourishes AI Agents with clean, structured context\n\n## Features\n\n### Foundation (The Mail Proxy)\n- **Virtual Inboxes**: Create email addresses for your AI agents\n- **Webhook Ingestion**: Receive emails from Mailgun, SES, SendGrid, Resend\n- **IMAP/SMTP**: Poll existing mailboxes (IMAP) and send via SMTP for any provider or self-hosted server\n- **Persistent Storage**: SQLite (default) or PostgreSQL with abstracted storage adapters\n- **Email Sending**: Send replies through your configured provider\n\n### Intelligence (The Agent Layer)\n- **Content Parsing**: HTML to clean Markdown, cruft removal\n- **Threading**: Automatic conversation grouping via email headers\n- **Thread Summarization**: LLM-generated thread summaries (OpenAI, Anthropic, Gemini) for list views and token savings\n- **MCP Server**: Connect directly to Claude, Cursor, and other MCP clients\n- **Attachment Processing**: Extract text from PDFs and documents\n\n### Enterprise (The Platform Layer)\n- **Semantic Search**: Vector embeddings with pgvector\n- **Real-time Webhooks**: Get notified of new messages\n- **Rate Limiting**: Protect against runaway agents\n- **Multi-Tenancy**: Organizations and projects\n\n## Quick Start\n\nTry NornWeave with no config: **demo mode** gives you a local sandbox and a pre-configured inbox.\n\n```bash\npip install nornweave[mcp]\nnornweave api --demo\n```\n\nAPI: `http://localhost:8000`. Open `/docs`, call `GET /v1/inboxes` to get the demo inbox id, then use MCP (`nornweave mcp`) to send and list messages. When you're ready for real email, set a provider and domain (see below).\n\n### Install options\n\n```bash\n# Base (SQLite, Mailgun/SES/SendGrid/Resend)\npip install nornweave\n\n# With IMAP/SMTP support\npip install nornweave[smtpimap]\n\n# With PostgreSQL\npip install nornweave[postgres]\n\n# With MCP server (recommended for agents)\npip install nornweave[mcp]\n\n# Full\npip install nornweave[all]\n```\n\n### Real email (after demo)\n\nCreate a `.env` file and set your provider and domain:\n\n```bash\n# .env — for inbox creation with a real provider\nEMAIL_PROVIDER=mailgun   # or ses, sendgrid, resend, imap-smtp\nEMAIL_DOMAIN=mail.yourdomain.com\n# ... plus provider-specific keys (see .env.example)\n```\n\nSee [Configuration](https://nornweave.datacovey.com/docs/getting-started/configuration/) for all settings.\n\n```bash\nnornweave api\n```\n\nData is stored in `./nornweave.db` (SQLite default).\n\n### Using Docker (Recommended for Production)\n\n```bash\n# Clone the repository\ngit clone https://github.com/DataCovey/nornweave.git\ncd nornweave\n\n# Copy environment configuration and set EMAIL_DOMAIN + provider keys (see above)\ncp .env.example .env\n\n# Start the stack\ndocker compose up -d\n\n# Run migrations (PostgreSQL only — SQLite tables are created automatically)\ndocker compose exec api alembic upgrade head\n```\n\n### Using uv (Development)\n\n```bash\n# Clone the repository\ngit clone https://github.com/DataCovey/nornweave.git\ncd nornweave\n\n# Install dependencies\nmake install-dev\n\n# Copy environment configuration and set EMAIL_DOMAIN + provider keys (see above)\ncp .env.example .env\n\n# Run migrations (PostgreSQL only — SQLite tables are created automatically)\n# make migrate\n\n# Start the development server\nmake dev\n```\n\n## API Overview\n\n### Create an Inbox\n\n```bash\ncurl -X POST http://localhost:8000/v1/inboxes \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"Support Agent\", \"email_username\": \"support\"}'\n```\n\n### Read a Thread\n\n```bash\ncurl http://localhost:8000/v1/threads/th_123\n```\n\nResponse (LLM-optimized):\n```json\n{\n  \"id\": \"th_123\",\n  \"subject\": \"Re: Pricing Question\",\n  \"messages\": [\n    { \"role\": \"user\", \"author\": \"bob@gmail.com\", \"content\": \"How much is it?\", \"timestamp\": \"...\" },\n    { \"role\": \"assistant\", \"author\": \"agent@myco.com\", \"content\": \"$20/mo\", \"timestamp\": \"...\" }\n  ]\n}\n```\n\n### Send a Reply\n\n```bash\ncurl -X POST http://localhost:8000/v1/messages \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"inbox_id\": \"ibx_555\",\n    \"reply_to_thread_id\": \"th_123\",\n    \"to\": [\"client@gmail.com\"],\n    \"subject\": \"Re: Pricing Question\",\n    \"body\": \"Thanks for your interest! Our pricing starts at $20/mo.\"\n  }'\n```\n\n## MCP Integration\n\nNornWeave exposes an MCP server for direct integration with Claude, Cursor, and other MCP-compatible clients.\n\n### Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `create_inbox` | Provision a new email address |\n| `send_email` | Send an email (auto-converts Markdown to HTML) |\n| `search_email` | Find relevant messages in your inbox |\n| `wait_for_reply` | Block until a reply arrives (experimental) |\n\n### Configure in Cursor/Claude\n\n```bash\npip install nornweave[mcp]\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"nornweave\": {\n      \"command\": \"nornweave\",\n      \"args\": [\"mcp\"],\n      \"env\": {\n        \"NORNWEAVE_API_URL\": \"http://localhost:8000\"\n      }\n    }\n  }\n}\n```\n\n## Architecture\n\nNornWeave uses a thematic architecture inspired by Norse mythology:\n\n| Component | Name | Purpose |\n|-----------|------|---------|\n| Storage Layer | **Urdr** (The Well) | Database adapters (PostgreSQL, SQLite), migrations |\n| Ingestion Engine | **Verdandi** (The Loom) | Webhook + IMAP ingestion, HTML→Markdown, threading, LLM thread summarization |\n| Outbound | **Skuld** (The Prophecy) | Email sending, rate limiting, webhooks |\n| Gateway | **Yggdrasil** | FastAPI routes, middleware, API endpoints |\n| MCP | **Huginn & Muninn** | Read resources and write tools for AI agents |\n\n## Supported Providers\n\n| Provider | Sending | Receiving | Auto-Route Setup |\n|----------|---------|-----------|------------------|\n| Mailgun | yes | yes | yes |\n| AWS SES | yes | yes | manual |\n| SendGrid | yes | yes | yes |\n| Resend | yes | yes | yes |\n| IMAP/SMTP | yes (SMTP) | yes (IMAP polling) | config |\n\n## Documentation\n\n- [Getting Started Guide](https://nornweave.datacovey.com/docs/getting-started/)\n- [API Reference](https://nornweave.datacovey.com/docs/api/)\n- [Architecture Overview](https://nornweave.datacovey.com/docs/concepts/architecture/)\n- [Provider Setup Guides](https://nornweave.datacovey.com/docs/guides/)\n\n## Repository Structure\n\nThis is a monorepo:\n\n| Directory | Purpose |\n|-----------|---------|\n| **`src/nornweave/`** | Main Python package: adapters (Mailgun, SES, SendGrid, Resend, SMTP/IMAP), core config, models, **huginn** (MCP resources), **muninn** (MCP tools), **skuld** (outbound/sending), **urdr** (storage, migrations), **verdandi** (ingestion, parsing, threading), **yggdrasil** (FastAPI gateway), search, storage backends |\n| **`clients/python/`** | Python client SDK (`nornweave-client`) |\n| **`packages/n8n-nodes-nornweave/`** | n8n community node for NornWeave |\n| **`tests/`** | Test suite: `fixtures/`, `integration/`, `unit/`, `e2e/` |\n| **`web/`** | Hugo documentation site (`content/docs/`) |\n| **`scripts/`** | DB init, migrations, dev setup |\n| **`skills/`** | Distributable AI assistant skills (e.g. `nornweave-api`) |\n| **`openspec/`** | Specs (`specs/`) and change artifacts (`changes/`, `changes/archive/`) |\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nNornWeave is open-source software licensed under the [Apache 2.0 License](LICENSE).\n\n---\n\n<p align=\"center\">\n  <sub>Image: \"Nornorna spinner odet tradar vid Yggdrasil\" by L. B. Hansen</sub><br>\n  <sub><a href=\"https://commons.wikimedia.org/w/index.php?curid=164065\">Public Domain</a></sub>\n</p>\n"}