# Batuda

> Open-source CRM with a built-in research agent. Find people, email them, follow up, remember the trail. Your providers, your budget. MCP-ready, MIT.

- **Type:** MCP server
- **Install:** `agentstack add mcp-guillempuche-batuda`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [guillempuche](https://agentstack.voostack.com/s/guillempuche)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [guillempuche](https://github.com/guillempuche)
- **Source:** https://github.com/guillempuche/batuda
- **Website:** https://batuda.co

## Install

```sh
agentstack add mcp-guillempuche-batuda
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Batuda

[](LICENSE)

**An open-source CRM with a built-in research agent. Find people, email them, follow up, and remember the trail.**

I built Batuda for the cases where a CRM that just *stores the row* isn't enough. I wanted the same tool to go look the row up — read a company's site, find the right contact, summarise the competitor — and hand me a structured result I could act on, on my own search + LLM keys, on a budget I set per user.

## Contents

- [The motion, end-to-end](#the-motion-end-to-end)
- [Who I built it for](#who-i-built-it-for)
- [What's in it today](#whats-in-it-today)
- [How Batuda compares](#how-batuda-compares)
- [Tech stack](#tech-stack)
- [Quick start](#quick-start) · [Detailed walkthrough →](docs/getting-started.md)
- [Scripts](#scripts)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#license)

## The motion, end-to-end

1. **Find.** Launch a research job against your own search and LLM providers. Pick a mode (`prospect_scan`, `company_enrichment`, `contact_discovery`, `competitor_scan`) or go freeform. Each run lands as a structured record on a company, with per-user budgets, monthly caps, and explicit approval over the auto-approve threshold. Caching at every layer (search, scrape, extract, LLM) so re-runs don't re-spend.
2. **Contact.** Email from your own inbox. Any IMAP/SMTP provider — Infomaniak, Fastmail, M365, Gmail, anything. Outbound goes from your address. Inbound threads back onto the contact.
3. **Follow up.** Tasks and meetings carry the next step. Cal.com webhooks pull meeting state straight onto the contact.
4. **Remember.** An immutable interaction log captures every touch. Documents, proposals, and call notes hang off the same company. Multi-tenant Postgres, RLS-isolated workspaces, your data.

## Who I built it for

The same job — find someone, contact them, remember what happened — shows up in dozens of shapes. The ones I had in mind:

- A two-person agency tracking 80 local restaurants through proposals and follow-ups.
- A solo founder running a seed round across 120 angels and partners.
- A freelance designer staying in touch with 30 past clients without a paid CRM seat.
- A recruiter shortlisting candidates for a specific role.
- A journalist tracking sources, calls, and quotes for a long-form piece.
- A podcaster or author booking guests across a launch.
- An academic mapping potential collaborators for a paper or grant.
- A nonprofit development team tracking donors and funders.
- A community or event organiser keeping speakers and sponsors in one place.
- A consultant juggling 12 active proposals across past and future clients.
- A job seeker tracking applications, recruiters, and follow-ups.
- An open-source maintainer reaching out for sponsorships.

One instance, many workspaces. Run it alone, run it for a team, or host several workspaces under one roof.

## What's in it today

- **Research as a first-class capability.** Pluggable `SearchProvider`, `ScrapeProvider`, plus three language-model roles (`AgentLanguageModel`, `ExtractLanguageModel`, `WriterLanguageModel`). Brave wired today. Per-user policy in `user_research_policy`, clamped against a system hard ceiling. Hierarchical parent/child runs. Streaming SSE events you can watch live.
- **Five typed result schemas** — `CompanyEnrichmentV1`, `CompetitorScanV1`, `ContactDiscoveryV1`, `ProspectScanV1`, `Freeform`. The agent returns a record, not prose.
- **Email through your own inbox.** IMAP IDLE in a separate `mail-worker` process. Credentials AES-256-GCM-encrypted per inbox. Outbound via SMTP, footer injection, draft staging.
- **Pipeline you can read at a glance.** Companies and contacts with status, priority, next action, last-contacted-at. Company-first, not deal-first.
- **MCP-first agent surface.** First-party MCP server with OAuth 2.1, intent-level typed tools (`search_companies`, `log_interaction`, `create_research`, `send_email`, …), slug-completion resources, and guided prompts. Claude, ChatGPT, and n8n use the same surface you do.
- **Multilingual page publishing** (Tiptap JSON blocks, `ca`/`es`/`en`) when you want a public landing for a workspace.
- **MIT, multi-tenant, your Postgres.** RLS-isolated workspaces, Better Auth, app-user / app-service roles.

## How Batuda compares

| Project         | Web research                              | Open source | Provider choice     | Budget control            | First-party MCP    |
| --------------- | ----------------------------------------- | ----------- | ------------------- | ------------------------- | ------------------ |
| **Batuda**      | First-class service + 5 typed schemas     | **MIT**     | **Pluggable ports** | **Per-user policy + cap** | **Yes**            |
| Attio           | Workflow block on a record                | Closed      | Their stack         | AI credits                | Yes                |
| Folk            | "Research Assistant"                      | Closed      | Their stack         | Per-plan                  | Community wrappers |
| Lightfield      | Code execution over interaction memory    | Closed      | Their stack         | Per-seat                  | Listed             |
| Reevo           | Bundled prospect DB, light "research"     | Closed      | Their stack         | Seat + credits            | None mentioned     |
| Twenty          | None as first-class (workflow `ai-agent`) | Custom OSS  | Vercel AI SDK       | None                      | Yes                |
| Atomic CRM      | None                                      | MIT         | n/a                 | n/a                       | OAuth + RLS proxy  |
| EspoCRM / Suite | None                                      | AGPL        | n/a                 | n/a                       | None               |

The combination no one else ships in one tool: **MIT + your provider keys + per-user budget caps + typed research schemas + intent-level MCP**. Full surface-by-surface comparison: [`docs/crm-competitor-analysis.md`](docs/crm-competitor-analysis.md).

> **Status.** Pre-1.0. Schema rewrites happen in a single `0001_initial.ts` migration; expect breaking changes between releases until I cut a stable version.

## Tech stack

| Layer           | Technology                                          |
| --------------- | --------------------------------------------------- |
| Monorepo        | pnpm workspaces + Turborepo                         |
| Dev environment | Nix flake (Node 24 + pnpm + kraft)                  |
| Shared schema   | `packages/domain` — Effect Schema                   |
| CLI             | `apps/cli` — Effect CLI + @clack/prompts TUI        |
| Backend         | `apps/server` — Effect HTTP + MCP server            |
| Web app         | `apps/internal` — TanStack Start                    |
| Shared UI       | `packages/ui` — MD3 design tokens + BaseUI + Tiptap |
| Database        | Postgres (NeonDB)                                   |
| Deploy          | Unikraft via kraft CLI                              |
| Code quality    | Biome (lint + format) + dprint (markdown)           |

## Quick start

**Requires:** Node 24, pnpm 10, Docker + Docker Compose. If you use [Nix](https://nixos.org), `nix develop` drops you into a shell with Node + pnpm already pinned.

```bash
nix develop                 # or: install Node 24 + pnpm manually
pnpm install                # install dependencies
pnpm cli setup              # copy .env files from .env.example
pnpm cli services up        # start Postgres + MinIO via Docker
pnpm cli db migrate         # create CRM + auth tables
pnpm cli auth bootstrap-org # create first admin + their org (interactive)
pnpm cli doctor             # verify everything is healthy
# in 2 terminals:
pnpm dev:server             # API + MCP server
pnpm dev:internal           # Batuda web app
```

First time? See the [detailed walkthrough](docs/getting-started.md) for explanations of each step, env var guidance, and troubleshooting.

## Scripts

```bash
# CLI
pnpm cli setup         # copy .env files from examples
pnpm cli doctor        # check environment health
pnpm cli seed          # insert sample data (Taller fictitious tenant)
pnpm cli db migrate    # run database migrations
pnpm cli db reset      # drop schema + re-migrate (chain `pnpm cli seed` for sample data)
pnpm cli services up   # start Docker services
pnpm cli:tui           # interactive TUI menu

# Development
pnpm dev:server        # start API + MCP server
pnpm dev:internal      # start Batuda web app

# Build & lint
pnpm build             # build all packages
pnpm lint              # lint + format
pnpm check             # lint + format (CI mode)
```

## Documentation

**Run it**

- [Getting started](docs/getting-started.md) — first-run setup, auth bootstrap, troubleshooting.

**Understand the architecture**

- [Architecture](docs/architecture.md) — system design, data flow, deployment.
- [Backend](docs/backend.md) — Effect patterns, routes, MCP tools.
- [Research](docs/architecture.md#research) — the server-side agent loop, pluggable capability providers, citations, budget policy, and data-sourcing strategy. Batuda's biggest feature.
- [Frontend](docs/frontend.md) — design tokens, MD3, BaseUI, components.

**Strategic context**

- [CRM competitor analysis](docs/crm-competitor-analysis.md) — surface-by-surface comparison against Attio, Folk, Twenty, Atomic CRM, EspoCRM, and more. Source for the table above.
- [Agency workforce platform](docs/agency-workforce-platform.md) — deferred design note on what it would take to grow Batuda into a small-agency platform where AI and human workers share a queue.

**Operate it**

- [Observability](docs/observability.md) — logs, metrics, traces.
- [Runbooks](docs/runbooks.md) — operational procedures (auth secret rotation, etc.).

**Contribute**

- [AGENTS.md](AGENTS.md) — rules and patterns for AI coding assistants working in this repo.

## Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

## License

[MIT](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [guillempuche](https://github.com/guillempuche)
- **Source:** [guillempuche/batuda](https://github.com/guillempuche/batuda)
- **License:** MIT
- **Homepage:** https://batuda.co

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-guillempuche-batuda
- Seller: https://agentstack.voostack.com/s/guillempuche
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.