Causly Server
Causly Server is a local-first MCP server that gives an AI agent developer, sales, operations, and productivity capabilities through dynamically loaded tool packs.
Discover and call tools dynamically with
search_tools,load_toolset, anduse_tool.Read, create, overwrite, edit, copy, move, delete, and inspect files; list directories, build directory trees, create/delete directories, and search file names.
Run shell commands with confirmation and catastrophic-pattern checks.
Detect project type/health and run tests, lint, typecheck, and build commands.
Use founder workflows: leads, sales pipeline, contacts, deals, activity reports, CSV export, meeting transcription/notes/action items, and reminders.
Integrate with Google Calendar/Gmail, Telegram, SEO/Search Console, Git/GitHub, Vercel, Docker, Terraform, Postgres/MySQL, Supabase, Slack, Notion, Linear, Sentry, and a local encrypted secrets store.
Run higher-level workflows such as
ship_change,fix_ci,verify_ci_fix, anddeploy_project.Store data locally in SQLite/
~/.causly, with safety features including confirmation prompts, read-only mode, workspace limits, secret redaction, activity logs, and untrusted-content handling.
Builds and runs containers, views logs, manages images, executes commands, and works with Docker Compose.
Provides local Git operations such as status, diff, commit, branch, merge, stash, tags, and remotes.
Manages GitHub repositories, issues, pull requests, reviews, and Actions.
Finds failing GitHub Actions workflow runs, fetches failure logs, polls workflow status, and verifies CI fixes.
Searches, reads, sends, replies to, and forwards Gmail messages.
Manages Google Calendar events, checks free/busy times, finds meeting slots, and creates, updates, or deletes events.
Provides SEO keyword ideas, page audits, draft checks, and Search Console integration.
Lists, reads, creates, updates, and comments on Linear issues.
Runs MySQL queries and inspects database schemas.
Manages Notion pages, databases, blocks, and comments.
Manages Sentry projects and issues.
Interacts with Slack channels, messages, and threads.
Manages Supabase projects and organizations and runs SQL.
Sends Telegram alerts and reads messages sent to the user's bot.
Runs Terraform init, plan, and apply; manages state and workspaces; and creates PR plan comments.
Manages Vercel projects and deployments and performs HTTP health checks.
Causly Server
The open-source MCP server that turns any AI agent into your technical co-founder.
Most agents can write text. Causly Server gives them hands: they ship code, hunt for clients, track deals, take meeting notes, handle your calendar and remind you on Telegram, all from one conversation, all on your own machine.
npm install -g causly-server
causly-server initContents
Related MCP server: jt-mcp-server
Why Causly Server
A founder's week is not only code. It is also finding clients, following up, remembering what was promised in a call, and shipping without breaking things. Causly Server puts all of that behind one MCP server.
One server for build, sell, operate and grow. Git, GitHub, CI and deploys, but also leads, a sales pipeline, meeting notes, calendar, reminders and SEO.
Memory that survives the chat. Your pipeline, meetings and reminders live in a local SQLite file, so the agent can pick up tomorrow where it stopped today.
Local-first. Keys and data stay on your machine. There is no Causly cloud in the loop.
Safe by default. Risky actions need explicit confirmation, file access can be limited to one folder, and secrets are redacted from logs.
Light on your agent's context. Tools load in packs on demand instead of flooding the agent with hundreds of definitions.
One command setup.
initfinds Claude Desktop, Cursor and Windsurf and wires them up.
Quick start
Requires Node.js 22.13 or newer. Full guide: Getting started.
1. Install
npm install -g causly-server2. Connect your editors
causly-server initinit adds Causly Server to Claude Desktop, Cursor and Windsurf, whichever you have. It also prints the one-line command for Claude Code. Restart the editor afterwards.
3. Check everything
causly-server doctor4. Add keys for the services you use (optional)
causly-server setupFiles, git, shell, Docker and Terraform work with no keys at all. Add keys only for the services you want. Each key is checked live as you enter it.
Useful init options:
causly-server init --client cursor # pick editors instead of auto-detecting
causly-server init --workspace D:\my-project # limit file tools to one folder
causly-server init --toolsets research,pipeline,meetings # choose which packs load at startupWhat you can ask
"Find companies hiring React developers and add the best three to my pipeline."
"Save notes from my call with Acme: they want a demo next week, follow up on Friday."
"What is due this week? Include meeting action items and reminders."
"Prep me for my next meeting." (needs Google Calendar)
"Transcribe this recording and list the action items." (needs a Groq key)
"Ship this change: run the checks, open a pull request, tell me when CI is green."
"Audit this page for SEO and suggest keywords."
"Find a free slot on Thursday and create the event."
How it works
Your agent talks to Causly Server over MCP (stdio). Inside the server:
Tool router.
search_tools,load_toolsetanduse_toollet the agent find a tool and call it by name. Packs load on demand, anduse_toolworks even in editors that do not refresh their tool list mid-chat, so you do not need to restart.Safety layer. Permission levels, confirmation for risky actions, an optional workspace limit, secret redaction and an activity log.
Tool packs. About 245 tools grouped into packs (below).
Local store. SQLite for pipeline, meetings and reminders in
~/.causly, encrypted secrets, and your API keys in~/.causly/.env.Your services. GitHub, Vercel, Docker, Terraform, Postgres, Slack, Notion, Linear, Gmail, Google Calendar, Telegram and more, reached with your own keys.
Tool packs
These packs load at startup by default:
Pack | Tools | What it does |
files | 9 | Read, write, edit, copy, move and inspect files |
directory | 5 | List, create and delete directories; search file names |
command | 1 | Run shell commands with safety checks |
project | 7 | Detect project type and health; run build, tests, lint and typecheck |
research | 2 | Search the web and read pages as clean text |
leads | 3 | Find companies hiring (Hacker News, remote job boards) and public company contact details |
pipeline | 9 | Local sales pipeline: leads, deals, contacts, activity log, report, CSV export |
meetings | 9 | Transcribe recordings, save summaries, track action items, link to deals and calendar, prep for calls |
reminders | 3 | Follow-ups saved locally; ask what is due |
These load on demand, or you can add them to startup with causly-server toolsets add <name>:
Pack | Tools | What it does |
calendar | 8 | Google Calendar: events, free/busy, find meeting slots, create, update, delete |
gmail | 8 | Search, read, send, reply and forward |
telegram | 5 | Alert yourself, read messages sent to your bot |
seo | 4 | Keyword ideas, page audit, draft check, Search Console |
git | 20 | Status, diff, commit, branch, merge, stash, tags, remotes |
github | 27 | Repos, issues, pull requests, reviews, Actions |
workflow | 4 |
|
vercel | 11 | Projects, deployments, HTTP health checks |
docker | 18 | Build, run, logs, images, exec, Compose |
terraform | 20 | Init, plan, apply, state, workspaces, PR plan comments |
database | 8 | Postgres and MySQL queries and schema inspection |
supabase | 6 | Projects, organizations and SQL |
slack | 8 | Channels, messages and threads |
notion | 15 | Pages, databases, blocks and comments |
linear | 7 | List, read, create, update and comment on issues |
sentry | 8 | Projects and issues |
secrets | 6 | Encrypted local secrets store |
Manage startup packs:
causly-server toolsets # show what loads at startup
causly-server toolsets add github,gmail
causly-server toolsets remove seo
causly-server toolsets reset # back to the defaultsWorkflow tools
Single tools are building blocks. These combine them into verified outcomes:
ship_change: inspects changes, creates a branch, runs project checks, commits, pushes and opens a pull request.fix_ci: finds a failing GitHub Actions run and fetches the real failure output.verify_ci_fix: commits and pushes the fix, polls the workflow and confirms CI is green.deploy_project: checks health, runs tests and build, deploys, polls, and HTTP-verifies the live URL.
flowchart TD
A["You describe a task"] --> B["Agent edits files"]
B --> C["ship_change runs checks"]
C --> D["Commit, push, open PR"]
D --> E{"CI passes?"}
E -- "No" --> F["fix_ci gets failure logs"]
F --> G["Agent fixes the code"]
G --> H["verify_ci_fix pushes and confirms CI"]
H --> E
E -- "Yes" --> I["deploy_project deploys"]
I --> J["HTTP verification"]
J --> K["Shipped"]Configuration
Settings live in ~/.causly/.env (on Windows, C:\Users\<you>\.causly\.env). Manage them with the CLI instead of editing by hand:
causly-server setup # step by step, each key checked live
causly-server keys list # which keys are set (never the full value)
causly-server keys set NAME # hidden prompt
causly-server keys unset NAME
causly-server doctor --test # check every configured service liveChanges are picked up without restarting your editor.
Service | Variables | Notes |
GitHub |
| Fine-grained token: contents, issues, pull requests |
Vercel |
| Project must be Git-linked for deploys |
Supabase |
| Management API |
Slack |
|
|
Notion |
| Share each page or database with the integration |
Linear |
| Personal API key |
Sentry |
| Add |
Gmail |
| Run |
Google Calendar |
| Same Google client as Gmail |
Telegram |
| Create a bot with @BotFather, message it, then find your chat id with |
Groq (meeting transcription) |
| Free tier available. Audio is uploaded to Groq only when you confirm a transcription |
Secrets manager |
| 32-byte hex key you generate and keep |
Timezone (optional) |
| IANA name, e.g. |
Safety (optional) |
| One folder only, read tools only, extra variables for child processes. See Security |
Docker and Terraform need no key, only the CLI on your PATH. Postgres and MySQL take a connection string on each call. Transcribing recordings over 25 MB needs ffmpeg on your PATH.
Google setup (Gmail, Calendar, Search Console)
Google needs a one-time OAuth client that you own. It takes about five minutes.
Open Google Cloud Console and create or pick a project.
Enable the APIs you want: Gmail API, Google Calendar API, and optionally Google Search Console API.
Open Google Auth Platform. Under Branding, fill in the app name and your support email. Under Audience, choose External and add your own Google account as a test user.
Under Clients, choose Create client and pick Desktop app. A "Web application" client fails with
redirect_uri_mismatch. Copy the client ID and secret.Save them in Causly: run
causly-server setup, orcausly-server keys set GMAIL_CLIENT_IDandcausly-server keys set GMAIL_CLIENT_SECRET.Sign in once in your browser:
causly-server login google # Gmail and Calendar
causly-server login google all # also Search ConsoleAvoid the 7-day expiry. While your Google app is in Testing, Google expires the sign-in token every 7 days. Renew it any time with causly-server login google, or stop the expiry for good: in Google Auth Platform → Audience, click Publish app (In production). The Branding page from step 3 must be filled in first. For personal use you do not need Google verification; at sign-in you will see an "unverified app" warning, which is expected for your own client: choose Advanced, then continue.
Works with
Client | Setup |
Claude Desktop |
|
Cursor |
|
Windsurf |
|
Claude Code |
|
Any MCP client or agent framework | Spawn |
Tested with Claude Desktop, Cursor and Windsurf (the same use_tool call on a real repository in each), a plain JavaScript MCP client, and LangChain (JS) through @langchain/mcp-adapters.
A minimal custom agent in JavaScript:
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const client = new Client({ name: "my-agent", version: "1.0.0" });
// Find the install folder with: npm root -g
await client.connect(new StdioClientTransport({
command: "node",
args: ["<npm-root>/causly-server/index.js"],
}));
const { tools } = await client.listTools(); // search_tools, load_toolset, use_tool, ...
const result = await client.callTool({
name: "use_tool",
arguments: { tool: "git_status", arguments: { repo_path: "." } },
});
console.log(result.content[0].text);Security and privacy
Causly can touch your files, repositories and infrastructure, so the controls live in the server itself. See SECURITY.md to report a vulnerability.
Permission levels. Every tool is
READ,LOW,MEDIUM,HIGHorDESTRUCTIVE.HIGHandDESTRUCTIVEactions (deploys, merges, shell commands, deletes, raw SQL, Terraform apply and destroy, Docker removal) need approval.You approve, not the agent. When your editor supports MCP prompts (elicitation), it asks you, and the agent cannot answer for you. Other clients keep the explicit
confirm: trueflag. An optional~/.causly/policy.jsonsets allow, ask or deny per tool or per risk level, and a broken file blocks instead of allowing.Read-only mode.
CAUSLY_READ_ONLY=truekeeps only read tools. Everything else disappears from the tool list and is refused, whatever the policy says.Workspace limit.
causly-server init --workspace <folder>restricts file and command tools to one folder. It also covers Docker volumes, Compose files and project resources.Minimal child environment. Commands and tools you run get a small environment, not every key Causly holds.
CAUSLY_PASSTHROUGH_ENVadds names you choose.Command risk checks. Drive wipes, formatting and shutdown commands are blocked. Force-pushes,
DROP TABLE,curl | bashandsudoare flagged.Path protection. Writes and deletes inside protected system directories are blocked.
Secret redaction. Tokens, passwords and API keys are redacted before anything is written to logs.
Local encrypted secrets. The built-in secrets manager uses AES-256-GCM with a key you control. No external vault needed.
Untrusted content. Email and GitHub text the agent reads is marked as untrusted, so instructions hidden in it are not followed as yours.
Activity log. Every call is recorded in
logs/activity.logas structured JSONL (timestamp, operation ID, risk level, status, redacted input, duration). It rotates at 10 MB and keeps 5 files.Private files. Causly's own files in
~/.causlyare readable only by you and are written atomically.
More detail, settings and limits: Security.
Privacy. Causly Server has no Causly cloud and no Causly account. Your pipeline, meetings and reminders are stored in a local SQLite file, and your keys stay in ~/.causly/.env. Data leaves your machine only when you use a service you configured, for example GitHub, Gmail, Telegram, or Groq for transcription, and only to that service.
Optional BoundaryAttest receipts for ship_change, verify_ci_fix and deploy_project are described in the docs.
Command reference
causly-server Start the MCP server (your editor runs this)
causly-server init Set up Claude Desktop, Cursor and Windsurf
--client claude|cursor|windsurf|all
--workspace <folder>
--toolsets <list>
--no-setup
causly-server status One screen: editors, keys, pipeline, reminders, backup, updates
causly-server doctor [--test] Check your setup; --test also checks every key live
causly-server setup [service] Add API keys step by step
causly-server keys list | set NAME | unset NAME | open
causly-server login google [gmail,calendar,gsc|all]
causly-server toolsets [add|remove|reset]
causly-server backup [file] Save a copy of your pipeline, meetings and reminders
causly-server restore <file> [--yes] Put a backup back (current data is kept as a copy)
causly-server remove [--client <name>] Remove it from your editors
causly-server --versionTroubleshooting
Start with causly-server doctor. It tells you what is missing.
Problem | Fix |
| Open a new terminal so your |
Editor does not show the tools after | Quit the editor completely (including the system tray) and open it again. |
The agent cannot see a tool that is not loaded | Ask it to call the tool with |
Gmail or Calendar stopped working | Your Google token expired (7 days in Testing mode). Run |
| Your OAuth client is a "Web application". Create a Desktop app client instead. |
A reminder never reached Telegram | Set both |
Transcription fails on a large file | Install |
| Quit Claude Desktop, Cursor and any app using Causly Server, then run it again. |
A file or command is refused | A workspace limit may be on. Check |
FAQ
Is it free? Yes. It is MIT licensed, including for commercial use. The services you connect have their own pricing.
Does my data go to Causly? No. There is no Causly cloud in the loop. See Security and privacy.
Do I need every key? No. Add keys only for the services you use.
Which agents work with it? Any MCP client. It is tested with Claude Desktop, Cursor, Windsurf, a plain JavaScript client and LangChain (JS).
Why is my agent not calling a tool? It may be in a pack that is not loaded. Tell the agent to use use_tool, or add the pack with causly-server toolsets add <pack>.
How do I update? npm update -g causly-server. status and doctor tell you when a new version is out.
How do I back up my data? causly-server backup saves your pipeline, meetings and reminders to a file. causly-server restore <file> puts it back.
How do I remove it? causly-server remove takes it out of your editors. Then npm uninstall -g causly-server.
Is there a hosted version? Causly Hosted is in development. Join the waitlist.
Compatibility
Status | |
Node.js | 22.13 or newer (CI runs Node 22 and 24) |
Windows, macOS, Linux | Tested on every pull request in CI. Reports from real machines are welcome. |
Editors | Claude Desktop, Cursor, Windsurf (tested); Claude Code (command printed by |
Known limitations
vercel_create_deploymentanddeploy_projectneed the Vercel project to be Git-linked already.supabase_run_sqluses the Supabase Management API; some personal access tokens get a403for SQL.slack_search_messagesneeds a Slack user token with thesearch:readscope.docker_pushneeds registry authentication already configured on the host.Sentry
resolve_issue,ignore_issueandadd_commentneed a token with theevent:writescope.
Contributing, roadmap, license
CONTRIBUTING.md explains how to add a tool pack and the manual testing checklist. Please read the Code of Conduct too.
ROADMAP.md has what is planned next. CHANGELOG.md has release history.
License: MIT.
Want something custom built on this?
Need a custom MCP server, a specific integration, or a related service for your product or team? Reach out: nihal@causly.in
Causly Hosted
Do not want to run Causly Server yourself? Causly Hosted is a managed version, currently in development.
Available Tools
25 toolscopy_fileC
Copy a single file to a new location.
Inputs: source (required), destination (required).
create_directoryB
Create a new directory, including any missing parent directories.
Inputs: path (required).
create_fileA
Create a brand-new file. Fails if the file already exists (use write_file to overwrite).
Inputs: path (required), content.
delete_directoryA
Delete a directory. Recursive by default so it removes nested contents too. DESTRUCTIVE — requires confirm: true.
Inputs: path (required), confirm, recursive.
delete_fileA
Delete a single file. DESTRUCTIVE — requires confirm: true.
Inputs: path (required), confirm.
directory_treeB
Recursively build a tree view of a directory's contents (skips node_modules and .git).
Inputs: path (required), max_depth.
edit_fileA
Edit a file via exact string find-and-replace, without rewriting the whole file. old_str must match exactly and be unique unless replace_all is set.
Inputs: path (required), new_str (required), old_str (required), replace_all.
get_file_infoB
Get metadata about a file or directory: size, type, created/modified timestamps.
Inputs: path (required).
list_directoryC
List the immediate files and subfolders inside a directory.
Inputs: path (required).
load_toolsetA
Load one or more toolsets (e.g. 'git', 'github', 'docker') so their tools become available. Use search_tools to discover toolset names.
Inputs: toolsets (required).
move_fileC
Move or rename a file or directory.
Inputs: source (required), destination (required).
project_detectA
Detect a project's language, framework, and package manager by inspecting its manifest files.
Inputs: repo_path (required).
project_healthB
Get a health snapshot of a project: git cleanliness/ahead-behind, whether dependencies are installed, and which env files are present.
Inputs: repo_path (required).
project_infoB
Get structured project info: language, framework, package manager, resolved test/lint/typecheck/build commands, and current git branch/remotes.
Inputs: repo_path (required).
read_fileB
Read the full text content of a single file.
Inputs: path (required), encoding.
read_multiple_filesB
Read multiple files in a single call. Failures on individual files do not stop the batch.
Inputs: paths (required), encoding.
run_buildB
Detect and run the project's build command, returning stdout/stderr/exit_code.
Inputs: repo_path (required), timeout_ms.
run_commandA
Run a shell command in a given working directory (npm install, npm run build, pip install, tests, etc.). A short list of catastrophic patterns (drive wipes, format, shutdown) is blocked; everything else executes with full permissions. HIGH risk — requires confirm: true.
Inputs: cwd (required), command (required), confirm, timeout_ms.
run_lintC
Detect and run the project's lint command, returning stdout/stderr/exit_code.
Inputs: repo_path (required), timeout_ms.
run_testsB
Detect and run the project's test command, returning stdout/stderr/exit_code.
Inputs: repo_path (required), timeout_ms.
run_typecheckB
Detect and run the project's typecheck command, returning stdout/stderr/exit_code.
Inputs: repo_path (required), timeout_ms.
search_filesC
Recursively search for files/folders whose name contains a given pattern (case-insensitive).
Inputs: pattern (required), root_path (required), max_results.
search_toolsA
Find tools by keyword across ALL toolsets, including ones not loaded yet. Call with no query to list every toolset.
Inputs: limit, query.
use_toolA
Call any tool by name, even one that is not in your tool list yet (its toolset loads automatically). Use this when load_toolset says your client may not show new tools. Set describe=true to see a tool's parameters first.
Inputs: tool (required), describe, arguments.
write_fileB
Create or completely overwrite a file with new content. Creates parent directories if needed.
Inputs: path (required), content (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Most tools have clearly distinct purposes, especially the file CRUD/search operations and the run_* wrappers. A few boundaries are fuzzy: project_detect vs project_info overlap, and run_command overlaps with run_tests/run_lint/run_typecheck/run_build. search_tools, load_toolset, and use_tool are related but distinguishable.
All names use snake_case, giving a predictable surface. However, the pattern is not strictly verb_noun: directory_tree, project_info, project_health, and project_detect are noun-ish phrases while most others follow verb_noun. The deviation is minor and still readable.
Twenty-five tools is at the heavy end for this server, even though it spans filesystem operations, project automation, and dynamic toolsets. Some consolidation is possible, especially project_detect/project_info/project_health and the four run_* wrappers around run_command. The count is borderline rather than clearly wrong.
The filesystem surface covers create, read, write, edit, move, copy, delete, list, tree, search, and metadata, which is strong CRUD coverage. Project automation covers detection, health, test/lint/typecheck/build execution, and arbitrary commands. Minor gaps include directory copy and built-in git operations, though load_toolset can extend coverage.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- AlicenseBqualityDmaintenanceProduction-grade MCP server that gives AI agents safe access to your local dev environment: filesystem, databases, processes, and OpenAPI specs.1540 npm4MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that equips AI agents with dev workflow tools including GitHub project management, conventional commits, visual regression testing, Jira/Confluence integration, and a persistent memory knowledge graph.14 npmMIT
- FlicenseAqualityCmaintenanceMCP server that enables AI assistants to run multi-step agent pipelines (e.g., Issue Analyst → Code Writer → Test Runner → PR Opener) from conversations, with support for Devin, shell, Python, and HTTP agents.7-
- AlicenseNot gradedqualityDmaintenanceA free, open-source MCP server that gives AI agents real filesystem, terminal, git, and process control over your machine for inspection, diagnosis, and repair.MIT