executive-copilot
Integrates with Asana as a task provider, allowing AI assistants to access and manage assigned tasks, including overdue task retrieval.
Integrates with Gmail as an email provider, allowing AI assistants to access inbox emails, search messages, and track follow-ups on sent emails awaiting replies.
Integrates with Google Calendar as a calendar provider, allowing AI assistants to retrieve today's schedule, upcoming events, and prepare for meetings.
Scans Google Meet meeting transcripts to extract action items and follow-ups from meetings.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@executive-copilot What's on my schedule today and which emails need follow-ups?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Executive Copilot
An MCP (Model Context Protocol) server that provides AI assistants with access to an executive's digital workspace. Aggregates data from email, calendar, tasks, and documents to enable intelligent assistance.
Features
MCP Interface: Works with Claude Desktop, ChatGPT, Cursor, and any MCP-compatible client
Multi-Provider Architecture: Pluggable providers for Outlook, Gmail, Google Calendar, Asana, and more
Context Engine: Intelligently determines which information sources to consult
Memory Layer: Persistent knowledge base for organizations, people, and decisions
Automation Engine: Scheduled jobs for synchronization and briefings
Follow-up Detection: Automatically tracks sent emails awaiting replies
Transcript Scanning: Extracts action items from meeting transcripts (Google Meet)
Obsidian Meeting Notes: Writes Gemini meeting notes into your vault as dated sections per meeting series (the verbatim transcript goes to a linked note of its own), and lets the assistant search them
E-mail to Calendar: Finds e-mails that need a calendar entry (invites, appointments, school events, reservations) and adds the ones you approve to your default calendar
Related MCP server: google-mcp-server
Quick Start
Prerequisites
Python 3.12+
uv (Python package manager)
Installation
# Clone the repository
git clone https://github.com/gppsys/personalcopilot.git
cd personalcopilot
# Install dependencies
uv sync
# Copy and configure your settings
cp config/organizations.example.yaml config/organizations.yaml
# Edit config/organizations.yaml with your accounts
# Optional: local overrides and extra rules (all gitignored)
cp config/config.local.example.yaml config/config.local.yaml
cp config/context_rules.example.yaml config/context_rules.yaml
cp config/email_forward_rules.example.yaml config/email_forward_rules.yaml
# Initialize database
uv run copilot db init
# Run MCP server
uv run copilot mcpConnect to Claude Desktop
Add to your Claude Desktop configuration:
{
"mcpServers": {
"executive-copilot": {
"command": "uv",
"args": ["--directory", "/path/to/personalcopilot", "run", "copilot-mcp"]
}
}
}Architecture
┌─────────────────────────────────────────────────────────────────┐
│ MCP Layer │
│ (FastMCP server with tool definitions) │
├─────────────────────────────────────────────────────────────────┤
│ Service Layer │
│ (EmailService, CalendarService, ContextService, etc.) │
├─────────────────────────────────────────────────────────────────┤
│ Domain Layer │
│ (Models, Business Rules, Value Objects) │
├─────────────────────────────────────────────────────────────────┤
│ Infrastructure Layer │
│ (Providers, Repositories, Database, Config) │
└─────────────────────────────────────────────────────────────────┘Available MCP Tools
Tool | Description |
| Get recent inbox emails |
| Search emails with query |
| Get pending follow-ups and reminders |
| Get today's calendar events |
| Get upcoming events |
| Get assigned tasks |
| Get overdue tasks |
| Get context for upcoming meeting |
| Combined daily briefing |
| Get organization information |
| Unified search across sources |
| Search knowledge base |
| Write recent Gemini meeting notes into the Obsidian vault (dry run available) |
| Search-then-read access to the Obsidian vault through a local index (SQLite FTS5 + OpenAI embeddings, fused by rank): searches return short snippets, reads can target one section. Credential-looking values are redacted before indexing; |
| Surgical note edits (tick a checkbox, append to or replace within a section) with a backup and a diff |
| Propose calendar entries found in e-mail (nothing is created) |
| Accept or dismiss a proposal |
| Create an event; defaults to |
Running the Copilot
Docker (recommended)
# 1. Local settings for compose (gitignored)
cat > .env <<'ENV'
OBSIDIAN_VAULT_PATH=/absolute/path/to/your/vault
TZ=America/Mexico_City
ENV
# 2. Admin panel + automation on http://127.0.0.1:8090
docker compose up -d --buildOpen http://localhost:8090 for the workspace: today's agenda, Asana tasks and follow-ups, e-mail-to-calendar proposals, the Obsidian meeting notes (browse, search, edit, sync from Gemini) and a chat that can read all of it. Changes the chat suggests (new task, new event) appear as cards you confirm. Settings and account authorization live at http://localhost:8090/admin. The chat uses the server AI key configured under Settings → Credentials.
The Cuentas section lists every Google/Microsoft account and token-based
service (Asana, Slack, OpenAI) with a live health check, connect/reconnect,
disconnect, and the redirect URIs to register. Secrets are never sent to the
browser. It also sets the default calendar and the calendar that receives
events found in Outlook mail; those choices are saved to
config/ui_settings.yaml (gitignored), which overrides the other config files.
The Mapa de relaciones section draws how people, organizations, meeting series, Asana projects/tasks, upcoming events and delegations connect, built from Obsidian notes, the e-mail interaction log, Asana and the calendar.
The repo is bind-mounted, so config, credentials and SQLite files stay on the
host and code changes only need docker compose restart. The vault is mounted
at the same absolute path it has on the host. TZ matters: cron schedules in
config/automation.yaml run in the container's local time.
Point Claude Desktop at the running container (stdio):
{
"mcpServers": {
"executive-copilot": {
"command": "docker",
"args": ["exec", "-i", "copilot-admin", "/opt/venv/bin/python", "-m", "executive_copilot.mcp"]
}
}
}Clients that speak streamable HTTP (e.g. Claude Code) can use the opt-in HTTP service instead. It has no authentication and listens on localhost only:
docker compose --profile http up -d
claude mcp add --transport http executive-copilot http://127.0.0.1:8091/mcpOption A: With Background Automation
Run the server with automatic follow-up detection and scheduled jobs:
# Start admin panel + automation engine
uv run copilot serve
# In Claude Desktop config, connect to MCP server separatelyThis runs:
Admin panel at http://localhost:8080
Background automation (follow-up detection at 9am & 2pm, email sync, etc.)
Option B: Components Separately
# MCP server only (for Claude Desktop)
uv run copilot mcp
# Admin panel only (no automation)
uv run copilot admin
# Manual sync of pending replies
uv run copilot sync-repliesCLI Commands
Command | Description |
| Run admin panel with background automation |
| Run the MCP server (for Claude Desktop) |
| Initialize database tables |
| Run the admin web panel only |
| Manually scan sent emails for pending replies |
| Show current configuration |
| Run terminal configuration UI |
Configuration
Configuration is managed through YAML files in the config/ directory:
config.yaml- Base configurationorganizations.yaml- Organization definitions (create from.example.yaml)context_rules.yaml- Context engine rulesautomation.yaml- Scheduled job configuration
See Configuration Guide for details.
Development
# Install dev dependencies
uv sync --dev
# Run tests
uv run pytest
# Run linter
uv run ruff check .
# Type checking
uv run mypy srcSee Development Guide for detailed instructions.
Documentation
Personal Knowledge Management — private GitHub notes, MySQL index and reviewed changes
License
MIT
Available Tools
71 toolsclose_weekA
Close the week on the tech dashboard by saving a snapshot.
Persists the dashboard's headline metrics plus an executive note, keyed by ISO week. The dashboard resource injects this history so next week's view knows where this one ended. A week already closed is not overwritten unless force=True.
Inputs: done (required), clients (required), roadmap (required), week, +3 more. Returns: object
complete_asana_taskC
Mark an Asana task complete.
Inputs: task_id (required), account. Returns: object
complete_commitmentC
Mark a commitment as completed.
Inputs: commitment_id (required). Returns: object
complete_delegationC
Mark a delegation as completed.
Inputs: delegation_id (required). Returns: object
complete_follow_upA
Mark a follow-up as completed.
Shorthand for update_follow_up with status=completed.
Inputs: follow_up_id (required). Returns: object
create_asana_taskC
Create a task in Asana.
Inputs: title (required), account, due_date, project_id, +2 more. Returns: object
create_commitmentA
Create a new commitment manually.
Use this to track a promise that wasn't auto-detected.
Inputs: title (required), direction (required), tags, due_date, +5 more. Returns: object
create_delegationB
Create a new delegation manually.
Use this to track a task you've assigned to someone.
Inputs: title (required), assignee_email (required), tags, due_date, +3 more. Returns: object
create_email_draftC
Create an email draft.
Inputs: to (required), body (required), subject (required), cc, +1 more. Returns: object
create_follow_upB
Create a new follow-up item.
Use this to track items that need future attention, such as:
Waiting for a response from someone
Need to check back on a project status
Promised to follow up on a topic
Inputs: title (required), tags, due_date, priority, +3 more. Returns: object
draft_emailB
Draft a new email with AI assistance.
Creates an email draft based on context and instructions, matching your writing style from previous emails.
Inputs: to (required), context (required), subject (required), account, +2 more. Returns: object
draft_follow_upA
Draft a follow-up email for a message awaiting response.
Use this when you sent an email and haven't received a reply. Generates a polite follow-up that references the original message.
Inputs: account, thread_id, create_draft, follow_up_id, +1 more. Returns: object
draft_replyA
Draft a reply to an email thread with context awareness.
Analyzes the thread history, matches your writing style from sent emails, and considers any open commitments/delegations with the recipient.
Inputs: account (required), thread_id (required), create_draft, instructions. Returns: object
get_all_commitmentsC
Get all commitments in both directions.
Shows both:
Things I promised to others (i_promised)
Things others promised to me (they_promised)
Inputs: limit, include_completed. Returns: object
get_all_unread_emailsB
Get unread emails from ALL authorized email accounts.
This aggregates unread emails across Gmail and Outlook accounts, organized by organization.
Inputs: limit_per_account. Returns: object
get_briefing_summaryA
Get a quick one-line summary of your day.
Returns a summary like "3 meetings, 2 pending replies, 1 overdue task" without the full details - perfect for a quick status check.
Returns: Summary text and counts
Inputs: no named parameters. Returns: object
get_commitments_with_personC
Get commitments involving a specific person.
Inputs: email (required), include_completed. Returns: object
get_daily_briefingA
Get a quick daily briefing summary.
Lighter-weight version that just shows email and calendar counts. Use get_morning_briefing for the full comprehensive briefing.
Returns: Summary of unread emails and today's events across all accounts
Inputs: no named parameters. Returns: object
get_delegationsA
Get tasks you've delegated to others.
Shows things you've asked others to do, such as:
"Can you handle the client report?"
"Please review the contract by Friday"
"Could you coordinate with the team?"
Inputs: limit, include_completed. Returns: object
get_delegations_to_personC
Get delegations assigned to a specific person.
Inputs: email (required), include_completed. Returns: object
get_email_forward_rulesA
Get all configured email forward rules.
Shows rules that automatically forward emails based on sender, subject, or other criteria.
Returns: List of forward rules with their conditions and actions
Inputs: no named parameters. Returns: object
get_emails_from_senderA
Get emails from a specific sender across all accounts.
Inputs: sender (required), limit. Returns: object
get_email_summaryB
Get a summary of email status across all accounts.
Returns: Summary with unread counts per account and organization
Inputs: no named parameters. Returns: object
get_email_threadC
Get all emails in a conversation thread.
Inputs: account (required), thread_id (required). Returns: object
get_event_detailsC
Get detailed information about a specific calendar event.
Inputs: account (required), event_id (required), calendar_id. Returns: object
get_follow_upsA
Get follow-up items that need attention.
Returns pending follow-ups ordered by due date and priority. Overdue items are highlighted.
Inputs: limit, include_snoozed, include_completed. Returns: object
get_follow_ups_with_personC
Get follow-ups related to a specific person.
Inputs: person_email (required), include_completed. Returns: object
get_inboxA
Get inbox emails from a specific account or all accounts.
Inputs: limit, account, unread_only. Returns: object
get_meeting_contextA
Get relationship context for meeting attendees.
For each attendee, shows:
Relationship summary (last contact, interaction count)
Recent interaction history
Open commitments and follow-ups
Use this before meetings to be fully prepared.
Inputs: attendee_emails (required), history_limit. Returns: object
get_meeting_decisionsC
Get all decisions from a specific meeting.
Inputs: event_id (required). Returns: object
get_meeting_outcomeA
Get the recorded outcome for a specific meeting.
Inputs: event_id (required). Returns: object
get_morning_briefingA
Get a comprehensive morning briefing.
Aggregates:
Today's calendar events
Unread and urgent emails
Overdue items (follow-ups, commitments, delegations)
Pending replies awaiting response
What you're waiting on from others
Returns a summary like "3 meetings, 2 pending replies, 1 overdue item" along with full details for each category.
Returns: Complete briefing with summary and detailed sections
Inputs: no named parameters. Returns: object
get_my_commitmentsA
Get commitments I made to others.
Shows things I promised to do for other people, such as:
"I'll send you the report by Friday"
"I will review this and get back to you"
"Let me take care of that"
Inputs: limit, include_completed. Returns: object
get_my_tasksB
Get assigned tasks from Asana accounts.
Inputs: limit, account, include_completed. Returns: object
get_organization_emailsC
Get recent emails related to a specific organization.
Inputs: organization (required), limit. Returns: object
get_others_commitmentsB
Get commitments others made to me.
Shows things other people promised to do for me, such as:
"John said he'll send the proposal Monday"
"She will review it by end of week"
"They promised to get back to us"
Inputs: limit, include_completed. Returns: object
get_overdue_commitmentsA
Get all overdue commitments (both directions).
Returns commitments past their due date that haven't been completed.
Returns: Overdue commitments ordered by due date
Inputs: no named parameters. Returns: object
get_overdue_delegationsA
Get all overdue delegations.
Returns delegations past their due date that haven't been completed.
Returns: Overdue delegations ordered by due date
Inputs: no named parameters. Returns: object
get_overdue_follow_upsA
Get all overdue follow-ups.
Returns follow-ups that are past their due date and not completed.
Returns: Overdue follow-ups ordered by due date
Inputs: no named parameters. Returns: object
get_person_historyA
Get recent interaction history with a person.
Shows the last N interactions (emails, meetings, etc.) with someone. Useful for preparing for meetings or refreshing your memory.
Inputs: email (required), limit. Returns: object
get_recent_decisionsC
Get recent decisions from all meetings.
Inputs: limit, days_back. Returns: object
get_recent_meeting_outcomesC
Get recently recorded meeting outcomes.
Inputs: limit, days_back. Returns: object
get_relationship_summaryA
Get comprehensive relationship summary for a person.
Shows:
Last contact date and type
Days since last contact
Total interaction count (inbound/outbound)
Open commitments and follow-ups
Whether the relationship is stale
Use this before meetings to understand your relationship history.
Inputs: email (required), stale_threshold_days. Returns: object
get_slack_channel_historyC
Get recent Slack messages for a channel visible to the bot.
Inputs: channel_id (required), limit, cursor, account_id. Returns: object
get_stale_relationshipsA
Get important people you haven't contacted recently.
Returns a list of relationships that may need attention based on:
No contact in the specified number of days
Person's importance level
Use this to identify clients, partners, or colleagues you should reach out to.
Inputs: limit, days_threshold, min_importance. Returns: object
get_today_eventsA
Get today's calendar events from ALL authorized accounts.
Returns: Today's events aggregated from all calendar accounts
Inputs: no named parameters. Returns: object
get_upcoming_eventsC
Get upcoming calendar events from all accounts.
Inputs: hours. Returns: object
get_waiting_summaryA
Get a summary of what you're waiting on from each person.
Shows counts like "Waiting on: 3 items from Sarah, 2 from Mike". Groups pending delegations by assignee.
Returns: Summary per person with counts and oldest item age
Inputs: no named parameters. Returns: object
get_week_eventsB
Get calendar events for the next N days from all accounts.
Inputs: days. Returns: object
get_week_historyB
Get the tech dashboard's closed-week snapshots.
Returns every saved weekly snapshot (metrics + executive note), newest last, plus the current ISO week key.
Returns: Week history keyed by ISO week
Inputs: no named parameters. Returns: object
join_slack_channelA
Join a public Slack channel so the bot can read its history.
Inputs: channel_id (required), account_id. Returns: object
list_accountsA
List all configured accounts with authorization status.
Returns: All email and calendar accounts with their status
Inputs: no named parameters. Returns: object
list_calendarsA
List all calendars from all authorized accounts.
Returns: List of calendars grouped by account
Inputs: no named parameters. Returns: object
list_organizationsA
List all configured organizations with their accounts.
Returns: List of organizations with associated accounts and authorization status
Inputs: no named parameters. Returns: object
list_slack_channelsB
List Slack channels and conversations visible to the bot.
Inputs: limit, cursor, account_id, exclude_archived. Returns: object
list_task_projectsB
List Asana projects for configured task accounts.
Inputs: account. Returns: object
prepare_for_meetingB
Prepare comprehensive context for an upcoming meeting.
Gathers event details, attendee information, recent emails with attendees, related tasks, and optionally generates AI-powered talking points.
Inputs: account (required), event_id (required), calendar_id, include_ai_summary. Returns: object
record_meeting_outcomeB
Record the outcomes of a meeting.
Use this after meetings to capture:
What was decided
What's next (action items)
Key discussion points
Inputs: event_id (required), event_title (required), meeting_date (required), tags, +6 more. Returns: object
run_email_forward_nowA
Run email forward rules immediately.
Processes unread emails and forwards those matching rules. Normally runs automatically every 5 minutes.
Returns: Statistics about forwarded emails
Inputs: no named parameters. Returns: object
search_all_emailsB
Search emails across ALL authorized accounts.
Inputs: query (required), limit_per_account. Returns: object
search_commitmentsB
Search commitments by title, description, or original text.
Inputs: query (required), limit. Returns: object
search_decisionsB
Search the decision log.
Search for decisions made in meetings by text.
Inputs: query (required), limit. Returns: object
search_delegationsC
Search delegations by title or description.
Inputs: query (required), limit. Returns: object
search_follow_upsC
Search follow-ups by title or description.
Inputs: query (required), limit. Returns: object
search_slack_messagesC
Search Slack messages visible to the authenticated app.
Inputs: query (required), page, count, account_id. Returns: object
send_briefing_emailC
Send the morning briefing as an email digest.
Generates a comprehensive briefing and sends it as a formatted email. Useful for receiving your daily summary in your inbox.
Inputs: account, to_email. Returns: object
send_emailB
Send an email from one of your accounts.
Inputs: to (required), body (required), subject (required), cc, +2 more. Returns: object
slack_statusC
Check Slack connection status.
Inputs: account_id. Returns: object
test_email_forward_rulesA
Test email forward rules against recent emails (dry run).
Checks which emails would be forwarded without actually forwarding them. Useful for testing rules before enabling them.
Inputs: hours_back. Returns: object
update_delegationC
Update a delegation.
Inputs: delegation_id (required), notes, status, due_date, +1 more. Returns: object
update_follow_upA
Update a follow-up item.
Use this to:
Mark a follow-up as completed
Change priority or due date
Snooze until a later date
Add notes
Inputs: follow_up_id (required), notes, status, due_date, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 71 tools
There are three overlapping follow-up/commitment domains: follow_ups, commitments, and delegations. While each has distinct semantics (follow-ups to self, commitments bidirectional promises, delegations to others), tools like get_overdue_follow_ups vs get_overdue_commitments vs get_overdue_delegations create boundary confusion, and get_my_commitments vs get_others_commitments vs get_all_commitments adds further overlap. Draft tools (draft_reply, draft_follow_up, draft_email) also have somewhat blurred boundaries despite decent descriptions.
Tool names follow a consistent verb_noun pattern throughout (get_, create_, update_, complete_, search_, draft_, send_). Naming is largely predictable and consistent in snake_case. Minor deviations exist like get_follow_ups_with_person vs get_commitments_with_person vs get_delegations_to_person (inconsistent use of 'with' vs 'to'), and get_emails_from_sender vs get_organizations_emails uses varying prepositions.
71 tools is a very large surface area for a single executive-copilot server. The scope spans email, calendar, tasks, Slack, meetings, relationships, decisions, follow-ups, commitments, delegations, briefings, and a tech dashboard. While each domain adds tools legitimately, this breadth makes the tool set unwieldy and hard for an agent to navigate efficiently. This is well beyond the 'heavy' range of 25+ tools.
The three tracking domains (follow-ups, commitments, delegations) all have create/get/search/complete and overdue variants, which is quite complete. Email, calendar, meetings, and relationships have solid coverage. However, some gaps exist: email lacks update/move/archive capabilities, calendaring lacks event creation/deletion entirely, and the tech dashboard's close_week/get_week_history pair is oddly sparse (only two tools for an entire dashboard domain). The domain is extremely broad, so it's hard to call it truly complete.
Maintenance
Related MCP Connectors
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Give AI agents a real email address, vault, calendar, and task delegation via MCP.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
MCP server providing AI assistants with integration capabilities for QuickBooks Online.
1
Related MCP Servers
- AlicenseAqualityCmaintenanceAn MCP server providing comprehensive email capabilities via IMAP and SMTP, enabling AI assistants to read, search, send, manage, schedule, and analyze emails across multiple accounts.521,007 npm161LGPL 3.0
- FlicenseNot gradedqualityBmaintenanceAn MCP server that enables AI assistants to read, search, and act on Google Workspace services including Gmail, Drive, Docs, YouTube, and Calendar.-
- AlicenseNot gradedqualityFmaintenanceAn MCP server that receives emails on your domain and allows AI assistants to search, read, and manage them via natural language queries.1,252 npmMIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to interact with Google Calendar and Gmail, allowing users to manage events, send emails, and organize their inbox through natural language.MIT