Open-source MCP server for startup and small business founders.
Founders OS gives you a complete business context - CRM, projects, tasks, finances, feeds, memory, playbooks - accessible from Claude, Cursor, or any MCP-compatible AI client. One connection, your entire business.
Built by OurThinkTank. Marketing site at foundersmcp.com.
New to AI tools, or handing this to someone who is? Start with Read This First - a plain-language intro to what FoundersOS is and isn't, what AI assistants can and can't do, and the habits that keep them honest.
| Module | Tools | Description |
|---|---|---|
| CRM | ||
| 13 | Customers, contacts, interactions, pipeline dashboard | |
| Tasks | ||
| 12 | Tasks with entity linking, AI assignment, dependencies, progress notes | |
| Projects | ||
| 5 | First-class project records anchored on a project tag, with task rollups | |
| Playbooks | ||
| 11 | Reusable orchestration templates that fan out to tasks and external MCP actions | |
| Tags | ||
| 4 | Shared tag registry with soft validation and auto-registration | |
| Financial | ||
| 14 | Double-entry ledger, P&L, multi-company, per-user access control | |
| Feeds | ||
| 13 | RSS/Atom/JSON reader, briefings, bookmarks, pins | |
| Memory | ||
| 5 | Semantic memory with personal + org scopes, pgvector, dedup, metadata filters | |
| Surfaces | ||
| 4 | Cross-domain reads: session start, entity cards, weekly retro, stuck list | |
| Members | ||
| 4 | Org membership directory, owner designation | |
| Audit + Restore | ||
| 2 | Full audit log; soft-delete recovery | |
| Diagnostic | ||
| 5 | Ping, version, usage guide, capability explorer, demos |
92 tools total across 12 modules.
You need a Supabase project, an embedding API key (OpenAI by default), and an MCP-capable AI client.
Create a Supabase project, then in the SQL Editor run supabase/setup.sql
. This single file sets up the full schema from scratch — extensions (vector
, uuid-ossp
, pg_trgm
), all tables, indexes, RLS policies, functions, views, maintenance jobs, and the Data API grants required for compatibility with Supabase's removal of automatic default privileges for projects created on or after 2026-05-30. The wizard at foundersmcp.com/setup prints the same SQL with the embedding dimension already matched to your provider — prefer it if you are not using the default dimension.
The Founders OS MCP server runs through npx
. Every client - Claude Desktop, Cowork, Cursor, Continue.dev, Zed, or any spec-compliant MCP client - uses the same configuration.
The quickest way is the wizard at foundersmcp.com/setup: enter your Supabase and embedding credentials and it generates a filled-in config for you to copy or download. Your credentials never leave the browser. You can also paste the block below by hand.
Drop this into your client's mcp.json
(in Claude Desktop, this is the MCP servers section of your config):
{
"mcpServers": {
"founders-os": {
"command": "npx",
"args": ["-y", "@ourthinktank/founders-os@latest"],
"env": {
"SUPABASE_URL": "https://your-project.supabase.co",
"SUPABASE_SECRET_KEY": "sb_secret_...",
"FOUNDERS_OS_COMPANY_ID": "your-company",
"FOUNDERS_OS_USER_ID": "your-name",
"FOUNDERS_OS_TIMEZONE": "America/Los_Angeles",
"EMBEDDING_PROVIDER": "openai",
"EMBEDDING_MODEL": "text-embedding-3-small",
"EMBEDDING_DIM": "1536",
"OPENAI_API_KEY": "sk-..."
}
}
}
}
See Environment variables for the full list and provider options.
What can you do? -> show_capabilities
Catch me up -> get_session_start
Add Acme Corp as a new prospect -> add_customer
Log a call with Sarah at Acme - discussed pricing -> log_interaction
Create a task to send the proposal by Friday -> create_task + link_task
What's stuck or overdue? -> get_stuck_list
Show me everything about Acme Corp -> get_entity_card
Remember for the org: targeting SMB fintech in Q3 -> memory_store
Show me OTT's P&L for Q1 -> get_pl_report
Run the customer-onboarding playbook for Acme -> run_playbook
Give me my weekly retro for LinkedIn -> get_weekly_retro
Pipeline management for customer organizations and the contacts inside them. Customers are organizations; contacts are people - always separate records, so you can move a contact between customers without losing history.
Customers: add_customer
, get_customer
, update_customer
, remove_customer
, search_customers
, list_customers
Contacts: add_contact
, update_contact
, remove_contact
, search_contacts
Interactions: log_interaction
, list_interactions
Dashboard: get_dashboard
Pipeline phases: prospect
-> lead
-> opportunity
-> customer
-> renewal
(plus churned
, inactive
).
Unified task management with org and personal scopes, entity linking, AI assignment, task dependencies, progress notes, and a task-to-memory bridge.
create_task
, get_task
, update_task
, complete_task
, remove_task
, list_tasks
, link_task
, unlink_task
, list_entity_tasks
, add_task_note
, assign_task
, get_task_summary
Scopes: org
(team-visible, default) and personal
(private to creator).
AI assignment: Use @claude
or @gpt
as the assignee. get_task_summary
surfaces a dedicated AI work queue. list_tasks(assigned_to='@claude')
filters to AI-assigned work.
Dependencies: Set blocked_by_task_id
on a task. Completing the blocker surfaces unblocked_tasks
in the response.
Task-to-memory bridge: When completing a task, set store_as_memory=true
to persist the completion note as an org-scoped memory entry.
Entity linking: Tasks can link to customers, contacts, interactions, transactions, projects, playbooks, memories, or any other entity type via the task_links
junction table. Link at creation time or later with link_task
.
Projects are first-class records anchored on a project tag (e.g. #acme-rebuild
). get_project
returns the project card with status, the linked tag, recent tasks grouped by status, and any customers tagged into it.
create_project
, get_project
, update_project
, remove_project
, list_projects
list_projects
also flags any #
-prefixed tags in the registry that don't yet have a project record, so the registry and the projects directory stay in sync.
Named, reusable orchestration templates. A playbook is defined once and run against a customer (or other subject) to spin up a complete project: it creates native Founders OS tasks AND, when connected MCP tools are present, fires external actions like creating a GitHub repo, posting to Slack, or scheduling a calendar event. If a connector is not available, the step gracefully falls back to a tagged [manual]
task so the playbook still works.
create_playbook
, get_playbook
, update_playbook
, remove_playbook
, list_playbooks
, add_playbook_step
, update_playbook_step
, remove_playbook_step
, run_playbook
, get_playbook_run
, list_playbook_runs
Step types: native_task
(Founders OS task) or external_action
(MCP tool call). External steps carry a connector
, an action
, and a params
object with placeholders.
Placeholders: {{customer.name}}
, {{customer.slug}}
, {{playbook.start_date}}
, {{playbook.start_date+Nd}}
, {{contact.primary.name}}
, {{memory:key}}
resolved at runtime.
Run log: get_playbook_run
returns the full execution log; list_playbook_runs
shows history per playbook.
Shared tag registry with soft validation. Tags are advisory: unrecognized tags warn but never block operations, and new tags auto-register on first use.
list_tags
, create_tag
, rename_tag
, remove_tag
Conventions: #project-name
for projects, @person
for people, !state
for meta-states (e.g. !needs-review
). Simple category words like bug
or release
are fine unprefixed.
Validation checks: typo detection against existing tags, known-contact detection (nudges toward @
), known-customer detection (nudges toward entity linking), and state-word detection (nudges toward !
).
Simple double-entry ledger scoped by FOUNDERS_OS_COMPANY_ID
, with per-user access control so company books can be opened to specific teammates only.
add_transaction
, list_transactions
, remove_transaction
, add_category
, list_categories
, remove_category
, add_account
, list_accounts
, remove_account
, transfer_between_accounts
, get_pl_report
, get_financial_summary
, get_financial_access
, set_financial_access
Multi-company: Set a different FOUNDERS_OS_COMPANY_ID
per instance to keep books separate.
Access control: set_financial_access
grants or revokes a member's access to a company's financial tools. get_financial_access
reports the current grants. By default the owner of a FOUNDERS_OS_COMPANY_ID
has access; everyone else is locked out until explicitly granted.
Built-in feed reader (RSS, Atom, JSON Feed) with a Postgres-backed store. Subscribe, brief, search, bookmark, pin.
Subscriptions: subscribe_feed
, unsubscribe_feed
, list_feeds
, refresh_feeds
, import_starter_feeds
, pin_feed
, unpin_feed
Items: get_feed_items
, read_feed_item
, get_feed_briefing
Bookmarks: bookmark_item
, remove_bookmark
, list_bookmarks
Categories: tech
, startups
, business
, finance
, product
, design
, engineering
, ai
, crypto
, science
, news
, personal
, other
.
Semantic memory backed by pgvector with personal and org scopes, near-duplicate detection, metadata filters, and pagination.
memory_store
, memory_recall
, memory_update
, memory_forget
, memory_summarize_and_store
Scopes:
org
-
visible to all team members pointing at the same Supabase project
personal -
visible only to the user whose
FOUNDERS_OS_USER_ID
matches
Filters on memory_recall:
min_score
, source_tool
, created_after
, created_before
, offset
, limit
, project
, scope
.Dedup: memory_store
and memory_summarize_and_store
check for existing memories with cosine similarity >= 0.92 and surface a conflict with options to force-store or skip.
Embedding providers (set via EMBEDDING_PROVIDER
):
| Provider | Default model | Dims | Credentials |
|---|---|---|---|
openai (default) |
|||
text-embedding-3-small |
|||
| 1536 | OPENAI_API_KEY |
||
bedrock |
|||
amazon.nova-2-multimodal-embeddings-v1:0 |
|||
| 1024 | AWS credential chain | ||
ollama |
|||
nomic-embed-text |
|||
| 768 | OLLAMA_BASE_URL |
Set
EMBEDDING_DIM
to match the model before running002_memory_schema.sql
. The dimension is permanent - changing providers later requires re-embedding the memory table.
Cross-domain read views that compose data from tasks, CRM, finance, and feeds into ready-to-render dashboards for AI agents.
| Tool | What it returns |
|---|---|
get_session_start |
|
| Orientation dashboard: task signals, AI queue, finance pulse, CRM activity, feed unread counts, suggested actions, first-run flag, and the four-tier rendering contract. Call at the start of every session. | |
get_entity_card |
|
| Complete picture of any entity (customer, contact, transaction, project) with open tasks, recent interactions, and linked records in one call. | |
get_weekly_retro |
|
| Completed-task retrospective grouped by tag with completion notes. Can format as a LinkedIn-ready draft. | |
get_stuck_list |
|
| Surfaces stuck, stale, and overdue tasks that need triage, with days-stale counts and suggested actions. |
Org membership directory. Maps FOUNDERS_OS_USER_ID
slugs to display names, marks the owner of a company, and supports adding or removing members.
add_member
, list_members
, remove_member
, set_member_owner
The owner of FOUNDERS_OS_COMPANY_ID
is the default holder of financial access; others get access via set_financial_access
.
get_audit_log
returns the structured audit trail across all domains (creates, updates, deletes, restores, financial access changes, playbook runs).
restore_item
reverses a soft delete on any soft-deleted record type, returning the record to its previous state. Use the audit log to find the original delete event and the entity ID to restore.
| Tool | Description |
|---|---|
ping |
|
| Connectivity test. Embeds an update notice if a newer package version is available. | |
get_version |
|
| Running package version, rendering contract version, and the latest npm-published version. | |
get_usage_guide |
|
| On-demand reference covering modules, conventions, and common workflows. | |
show_capabilities |
|
| Friendly overview with example prompts for each module. | |
list_demos |
|
| Lists or runs the bundled interactive walkthroughs (welcome tour, conflict resolution, run-my-week, etc.). |
Render-bearing tools include a render
field with a four-tier ladder so the AI client picks the most visual output it supports: visual primitive tool (artifact/widget/canvas), inline rich output (HTML/SVG/JSX), markdown table, then prose. The contract ships in three channels in attention-strength order:
Server at MCP registration - loaded at connect. All spec-compliant MCP clients.instructions
field- full ladder text on session orientation. All clients.get_session_start.rendering_contract
Per-response- self-contained short form. Cold-start safety net.rendering_contract
reminder
The canonical source lives in packages/mcp-server/src/contract.ts
, so every MCP client gets rich rendering through these channels with no plugin required. (A Claude plugin that mirrors the contract at system-prompt position, for stronger adherence in long sessions, is planned for a later release and is not part of this one.) Current contract_version
is 4
; a mismatch surfaces as contract_version_warning
on get_session_start
and get_version
.
When the database is empty, tools attach onboarding hints to their responses. get_session_start
detects a fresh install and suggests a guided walkthrough: add a first customer, create a first task, and optionally set up finance accounts. This keeps the experience conversational rather than dumping all 92 tools at once.
For a guided tour of a specific feature, ask the AI to "run the welcome demo" or "show me the conflict-resolution walkthrough" - list_demos
returns the bundled interactive scripts.
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SECRET_KEY=sb_secret_...
FOUNDERS_OS_USER_ID=your-name # defaults to "default"
FOUNDERS_OS_COMPANY_ID=your-company # defaults to "default"
FOUNDERS_OS_TIMEZONE=America/Los_Angeles # used by date-aware tools and YTD math
EMBEDDING_PROVIDER=openai # openai | bedrock | ollama
EMBEDDING_MODEL=text-embedding-3-small # provider default used if omitted
EMBEDDING_DIM=1536 # MUST match the vector() size in 002_memory_schema.sql
OPENAI_API_KEY=sk-...
git clone https://github.com/ourthinktank/founders-os.git
cd founders-os
npm install
npm run build
npm run dev
founders-os/
├── packages/
│ ├── mcp-server/ # @ourthinktank/founders-os npm package
│ │ ├── src/
│ │ │ ├── index.ts # Entry point (stdio transport)
│ │ │ ├── supabase.ts # Database client
│ │ │ ├── contract.ts # Canonical rendering contract
│ │ │ └── tools/
│ │ │ ├── crm/ # Customers, contacts, interactions, dashboard
│ │ │ ├── tasks/ # Task management
│ │ │ ├── projects/ # Project records
│ │ │ ├── playbooks/ # Reusable orchestration templates
│ │ │ ├── tags/ # Shared tag registry
│ │ │ ├── financial/ # Ledger + access control
│ │ │ ├── rss/ # Feed reader
│ │ │ ├── memory/ # Semantic memory
│ │ │ ├── surfaces/ # Cross-domain reads
│ │ │ ├── members/ # Org directory
│ │ │ ├── audit.ts # Audit log
│ │ │ ├── restore.ts # Soft-delete recovery
│ │ │ ├── diagnostic.ts # Ping + version
│ │ │ ├── meta.ts # Usage guide + capabilities + demos
│ │ │ ├── first-run.ts # Empty-database hints
│ │ │ ├── dates.ts # Date/timezone helpers
│ │ │ └── permissions.ts # Financial access checks
│ │ └── demos/ # Interactive walkthrough scripts
├── integrations/
│ └── setup-page/ # Config wizard hosted at foundersmcp.com/setup
├── supabase/
│ ├── setup.sql # Complete schema for fresh installs (run once)
│ └── migrations/ # Future schema changes (empty at launch)
├── docs/ # Specs and design docs
└── README.md
Build, then point your MCP client at the local entry instead of npx:
{
"mcpServers": {
"founders-os": {
"command": "node",
"args": ["/absolute/path/to/founders-os/packages/mcp-server/dist/index.js"],
"env": {
"SUPABASE_URL": "https://your-project.supabase.co",
"SUPABASE_SECRET_KEY": "sb_secret_...",
"FOUNDERS_OS_USER_ID": "your-name",
"FOUNDERS_OS_COMPANY_ID": "your-company",
"EMBEDDING_PROVIDER": "openai",
"EMBEDDING_DIM": "1536",
"OPENAI_API_KEY": "sk-..."
}
}
}
}
Founders OS is open source under the MIT license. Outside contributions are not being accepted yet - that's coming soon. In the meantime, issue reports are welcome and very much encouraged: please file them on GitHub. See CONTRIBUTING.md for how to file a good report, and our Code of Conduct. Security issues should go through SECURITY.md, not public issues.
MIT - see LICENSE.