Capes

Give Claude, Codex, Cursor and any MCP client hands: your Gmail, Discord and X, through one private server you own.

🚀 Start Quick start Deploy Connect a client

💡 Learn What you get A day with Capes How it works

⚙️ Reference Services Dashboard All 68 tools

💬 Community What's built What's next Request a feature · ☕ Support

🤝 Project Security Contributing Documentation

🎬 Demo

▶ Watch the demo on YouTube

Fresh Vercel deploy, checking connectors, browsing all 68 tools, connecting a client, and asking Claude to use it.

✨ What you get

AI assistants read, summarise and act well, but your real work lives in accounts they cannot reach. Capes is one private MCP server that you deploy to your own Vercel account. Connect it once and the same tools appear in every AI client you use.

🎬 A day with Capes

Sam runs a small product and its Discord community, and answers customers from one Gmail inbox. Every morning Sam asks one question in Claude:

Sam: Give me a briefing. Unread customer emails from the last day, unanswered questions in #support, and what people are saying about our product on X.

The assistant, using tools from the same server:

1. gmail_search for is:unread newer_than:1d, then gmail_get_message on the ones that look like customers. It groups them: 3 billing questions, 1 bug report, 2 newsletters.
2. discord_read_channel on #support, and finds 4 questions nobody answered.
3. twitter_search for the product name, and summarizes the tone of 20 recent tweets.

Sam: Draft replies to the billing emails, and answer the two easy Discord questions. Show me everything before you send.

1. gmail_create_draft for each reply (drafts, nothing sent yet).
2. Shows Sam the drafts and the two Discord answers. Sam approves.
3. gmail_send_draft, discord_send_message, and gmail_modify to label and archive the handled mail.

That is about five minutes instead of forty, and the assistant never had direct access to Sam's accounts: everything went through Sam's own server, with Sam's own limits. When Sam wants an assistant to only look, one switch in the dashboard hides every tool that sends or deletes.

This is an illustration of what the tools make possible, not a recording.

Why not just use each app's built-in connectors?

• One setup for every client. The same server works in Claude Desktop, Claude Code, Cursor and Codex, not just one app.
• You hold the credentials. They sit in your own Vercel project, not in a third-party platform.
• You set the limits. Switch connectors and single tools off, or make the whole server read-only, and see what was called.
• Free to run for personal use, and easy to extend with your own tools.

Other ways to solve this exist (hosted platforms like Composio, gateways like MetaMCP, single-service MCP servers). A short comparison is in What Capes is for.

🧭 How it works

Your server exposes POST /mcp, protected by a secret key you create (MCP_API_KEY), and a dashboard at /dashboard that you sign in to with the same key, or with a separate username/password if you set DASHBOARD_USER/DASHBOARD_PASSWORD (no third-party accounts either way). Every call passes a guard that checks the key, validates the arguments and applies your limits before a tool runs. Service credentials (Gmail app password, Discord bot token, Apify token) live as Vercel environment variables or, encrypted, in your own Postgres database -- never anywhere else.

Interactive diagrams (pan, zoom, search, trace a path): architecture, life of a tool call and how a change reaches main. GitHub shows an HTML file as source, so click the link, choose Download raw file (the download icon), and open the file in your browser. It is self-contained and works offline.

🚀 Quick start

About 20 minutes, most of it creating credentials. Skip any service you do not need.

🔌 Services and credentials

Click a guide for the exact steps, permissions and limits of each service.

MCP_API_KEY, ENCRYPTION_KEY, DATABASE_URL, DASHBOARD_USER and DASHBOARD_PASSWORD are required. Discord/Gmail/Apify/Telegram are all optional -- a tool whose credentials are missing returns a clear message instead of failing.

☁️ Deploy

Option A: deploy on Vercel (recommended)

No install, no terminal.

1. Click the button and sign in to Vercel. It copies the repository into your GitHub account.

2. Paste MCP_API_KEY and ENCRYPTION_KEY (how to make them, two different random strings), a DASHBOARD_USER/DASHBOARD_PASSWORD you pick (same section), and DATABASE_URL (get a free one from Supabase). These five are required. If you already have credentials for Discord, Gmail, Apify or Telegram, click Add More on the same screen and add them now. Otherwise, deploy first and add them later, either one at a time in Settings > Environment Variables, or all at once from a clone of the repo:

    node scripts/capes.mjs env --name <your-project-name>

   It asks for each service credential once, sets them all and redeploys — never touches MCP_API_KEY or a client you've already connected.

3. Click Deploy, then open https://<project>.vercel.app/dashboard and sign in with your DASHBOARD_USER/DASHBOARD_PASSWORD.

The button works for anyone once the repository is public. Before that, or from a fork, use Vercel > Add New > Project > Import Git Repository, choose the repo and add the same variables. Details, Deployment Protection and key rotation: Vercel guide.

Option B: one command from your computer

Needs Node.js 18+ and a Postgres DATABASE_URL (free: supabase.com). It logs you in to Vercel, generates strong keys, asks for your database URL, dashboard username/password, and service credentials (Enter skips optional ones), deploys, connects your AI clients and prints your Discord invite link:

git clone https://github.com/Dipeshpal/capes.git
cd capes
node scripts/capes.mjs install

Your address, key and encryption key are saved to .capes.local.json (git-ignored). Non-interactive: node scripts/capes.mjs install --name my-capes --database postgres://... --dashboard-user admin --dashboard-password your8pluscharpassword --discord TOKEN --apify TOKEN --gmail you@gmail.com --gmail-password APP_PASSWORD --clients desktop,cursor.

Option C: Vercel CLI by hand

Step by step in the Vercel guide.

Updating an existing deployment

When new features land, pull them into your own deployment: node scripts/capes.mjs update from a clone (fetches upstream, merges, redeploys). Details: Vercel guide.

🖥️ The dashboard

Open https://<project>.vercel.app/dashboard and sign in with your DASHBOARD_USER/DASHBOARD_PASSWORD (or MCP_API_KEY, if you didn't set those).

Overview: what clients can see and your endpoint Connectors: test credentials, get the Discord invite link

• Overview, Connectors, Tools: what is connected and which tools clients can see.
• Test connection: a read-only check of each service's credentials.
• Limits: turn a service or a single tool off, or hide everything that changes data. Set PULSE_READ_ONLY, PULSE_DISABLED_CONNECTORS or PULSE_DISABLED_TOOLS on Vercel (an optional free Redis, separate from your Postgres database, lets you flip these on the dashboard without redeploying).
• Try: run read-only tools with a form.
• Connect a client: copy-ready config for Claude, Cursor and Codex.

Full walkthrough and security details: Dashboard guide.

🤖 Connect your AI client

Every client needs your address https://<project>.vercel.app/mcp and your MCP_API_KEY as Authorization: Bearer <key>. The dashboard's Connect a client tab shows the exact config. Or, from a clone of the repo:

node scripts/capes.mjs connect        # configures Claude Desktop, Claude Code, Cursor, Codex

By hand, per client (client guide):

Restart the client after connecting so it loads the tools.

💬 Using it

Once connected, just talk to your assistant and it picks the tools:

• "How many unread emails do I have? Summarize the five newest."
• "Draft a reply to the last email from Sam. Show me before sending."
• "Read the last 50 messages in #support and list the open questions."
• "Post the release notes in #announcements and pin them."
• "Search X for people talking about MCP servers."

Sending mail and messages cannot be undone, so ask for a draft first when it matters. Using Capes has more examples and safety habits.

🧰 Tools

68 tools. The lists below are the quick view; docs/usage/tools.md is the generated reference with every tool's description, kind and arguments.

📧 Gmail (17)

gmail_search, gmail_get_message, gmail_get_thread, gmail_get_attachment, gmail_list_labels, gmail_send_email (HTML, cc/bcc, attachments), gmail_reply (reply-all, quoted original), gmail_forward, gmail_create_draft, gmail_list_drafts, gmail_send_draft, gmail_delete_draft, gmail_modify (read/unread, star, archive, labels), gmail_trash, gmail_mark_spam, gmail_create_label, gmail_delete_label

💬 Discord (47)

Read: discord_list_guilds, discord_get_guild, discord_list_channels, discord_get_channel (with permission overwrites), discord_read_channel, discord_get_message, discord_list_pins, discord_list_reactions, discord_list_members (search too), discord_list_roles, discord_list_emojis, discord_list_scheduled_events, discord_list_threads, discord_list_invites, discord_get_audit_log, discord_read_dm

Messages: discord_send_message (text, embeds, replies), discord_send_dm, discord_send_file (base64 upload), discord_create_poll, discord_edit_message, discord_delete_message, discord_bulk_delete_messages, discord_pin_message, discord_add_reaction, discord_remove_reaction

Channels and threads: discord_create_channel (text, voice, category, announcement, stage, forum, private), discord_edit_channel (also renames, archives and locks threads), discord_delete_channel, discord_set_channel_permission, discord_delete_channel_permission, discord_create_invite, discord_delete_invite, discord_create_thread (from a message, standalone, private, or forum post with tags), discord_thread_member

Forums and webhooks: discord_list_forum_tags, discord_manage_forum_tag, discord_list_webhooks, discord_create_webhook, discord_send_webhook_message (the webhook token never leaves the server), discord_delete_webhook

Roles and moderation: discord_create_role, discord_edit_role, discord_delete_role, discord_member_role, discord_set_nickname, discord_moderate_member (kick, ban, unban, timeout)

🐦 X / Twitter (1)

twitter_search

✈️ Telegram (3)

telegram_send_message, telegram_get_chat, telegram_get_updates

Tools are flagged read, write or destructive so clients can ask before risky calls, and you can switch any of them off in the dashboard. Discord channel and thread IDs are interchangeable wherever a channel_id is asked for.

✅ Check that it works

1. Open /dashboard, sign in, and click Test connection on each connector.
2. Or curl https://<project>.vercel.app/health returns "status":"online".
3. In your AI client, ask "List my Discord channels" (Discord), "How many unread emails do I have?" (Gmail) or "Search X for MCP servers" (Apify).
4. Something wrong? Troubleshooting maps every common error to its fix.

🏁 What's built

• [x] 68 tools across four services: Gmail (17), Discord (47), X search (1) and Telegram (3). The Discord toolkit covers messages, DMs, files, polls, threads, forums, webhooks, channels, roles, permissions, moderation, invites and the audit log.
• [x] Owner dashboard: sign in with your key, test each connector, browse the tools, try read-only ones, watch activity, copy client config, and generate your Discord invite link in one click.
• [x] One-click deploy to your own Vercel (Deploy button or one installer command). Needs a free Postgres database (e.g. Supabase) for credentials and API keys.
• [x] Works in Claude Desktop, Claude Code, Cursor and Codex (and any client that speaks MCP over HTTP).
• [x] Limits you control: switch a service or a single tool off, or make the whole server read-only. Every tool is labelled read, write or destructive.
• [x] Built to be safe: arguments validated against each tool's schema, secrets redacted from errors and logs, signed dashboard sessions with CSRF protection, rate-limited sign-in, fail-closed settings.
• [x] Tested without credentials: a fake IMAP server and a fake Discord API server exercise the tools in CI. Most Discord tools were also run against a real test server; one of 33 checks failed on the first run, and it was a real bug (pinning needs the separate Pin Messages permission), which is fixed. The maintainer has since tested it on a real community server too.
• [x] Open-source ready: MIT license, contributor guard against unreviewed changes to CI and assistant settings, protected main (pull request, code-owner review and green checks), secret scanning, docs with diagrams.
• [x] Bring-your-own Postgres for credentials and API keys: connector tokens encrypted in your own database, multiple labelled/expiring MCP API keys managed from the dashboard's Settings tab, all optional for existing deployments (#38, #39). New deploys (Deploy button and installer) now provision it by default (#40), plus a separate dashboard username/password login (#41, #42).
• [x] node scripts/capes.mjs update: pull new capes releases into your own deployed fork and redeploy in one command, database migrations run automatically (#43).

🗺️ What's next

Ideas, not promises. What you ask for moves up the list, so tell us what you need.

• [x] Discord: scheduled events, emoji listing, nicknames. Community-contributed (#25, #26) plus discord_set_nickname. Still open: application commands, stickers.
• [x] A second connector: Telegram. Send messages, read chat info, poll updates (#33). More services welcome — claim one.
• [x] A short demo video of an assistant using the tools, linked at the top of this README.
• [x] A fresh-account walkthrough of the README and Deploy button. Found and fixed a real bug: the button listed optional service credentials as required, contradicting "leave them empty" (#31).
• [x] v1.0.0 tagged release, with release notes.
• [ ] Per-client keys and scopes, so one assistant can be read-only while another is not. Design posted for discussion in #24; implementation not started.
• [ ] Verify the optional Redis settings on a real Upstash database (today they are tested against a fake server) — in progress.
• [ ] Multiple accounts per service (for example two mailboxes).
• [ ] More connectors: calendar, chat and notes tools are natural next candidates.

The design notes and known limits are in What Capes is for.

📬 Request a feature or a new MCP connector

Want your assistant to reach another service, or a tool that is missing?

Open a feature request and tell us:

• what you want to be able to ask your assistant to do,
• for a new service: its API docs, how a user gets credentials (token, app password, OAuth), whether it is free for personal use, and whether it works over plain HTTP from a short-lived serverless function,
• the tools you would like (name, what it does, read, write or destructive),
• whether you plan to build it yourself.

Want to build it? A new tool is one Python function; a whole service is a small module. Start with Contributing. Found a bug instead? Report it. Security problems go to SECURITY.md, not a public issue.

☕ Support the project

Capes is free and open source, built and maintained in spare time. If it saves you time, a coffee helps keep it going.

Starring the repo, sharing it, fixing a typo or sending a pull request helps just as much.

🛡️ Security

Capes holds real credentials, so it is built to be strict by default.

Details in SECURITY.md and the security model.

🤝 Contributing

Anyone can contribute: fix a bug, sharpen a guide, add a tool, or improve the dashboard. Only the maintainer merges. Nobody pushes to main; every change goes through a pull request that passes the checks and gets a code-owner review (Governance).

1. Read What Capes is for and Contributing.
2. Fork, branch (feat/..., fix/..., docs/...), make one focused change.
3. Run the checks (no credentials needed; the full list is in Contributing):

    uv run --with fastapi --with aiohttp --with python-dotenv --with httpx python tests/protocol.py
    uv run --with fastapi --with aiohttp --with python-dotenv --with httpx python tests/dashboard.py
    uv run --with fastapi --with aiohttp --with python-dotenv python tests/gmail_offline.py
    python tests/claude_config.py
    uvx ruff check . && uvx ruff format --check .

4. Open a pull request using the template. Say what you tested and what you could not. CI runs the same checks, a guard for assistant/CI configuration, and a secret scan.

Adding a tool takes one Python function:

# pulse/hello.py  (then import it in api/index.py)
from .registry import tool

@tool("hello", "Say hello", {"name": {"type": "string"}}, ["name"], hint="read")
async def hello(args: dict):
    return {"message": f"Hello {args['name']}"}

Changes to .claude/, .github/, scripts/, authentication code, vercel.json or dependencies always need the maintainer's review (see Security).

🧠 The .claude folder: the repo ships its own Claude Code setup

A contributor's assistant knows the project from the first prompt:

With Claude Code: run claude in the repo, then for example /add-tool slack slack_send_message, /run-tests, and ask @tool-reviewer to review your diff. What each file does is in docs/project/contributing.md.

📚 Documentation

Everything is indexed in docs/README.md.

📄 License

MIT. Use it, change it and share it; keep the copyright notice. It comes with no warranty, so you are responsible for what your AI assistants do with your mailbox and servers.

🔗 References

• Model Context Protocol: introduction and connecting Claude Code to MCP servers
• Claude Code directory layout, which the .claude/ folder follows
• Discord developer documentation
• Gmail IMAP extensions (search syntax, labels, threads) and Google app passwords
• Apify Tweet Scraper, the default actor behind twitter_search
• Vercel Functions and the Upstash Redis integration
• Inspiration: kebab-mcp showed how useful a dashboard on a personal Vercel MCP server can be. Capes's dashboard is an independent implementation written from scratch. The README layout draws on the structure of other well-presented open-source READMEs; the wording and content here are our own.