convez.ai
MCP ServerIntegração & APIsAvançado
olamide226

Personal MCP Server

olamide226/personal-mcp-server

Acesso seguro a email, Slack e knowledge base pessoal para agentes IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP privado que conecta agentes de IA ao seu email (Gmail/IMAP), notificações Slack e base de conhecimento pessoal. Oferece busca de mensagens, envio de emails com confirmação de segurança, postagem em Slack e gerenciamento de documentos pessoais via SQLite ou Turso.

Instalação

$npx convez-ai olamide226/personal-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
14%
Último commit
há 3 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Criar agentes que monitoram e respondem emails automaticamente
  • Integrar Slack com sistemas de notificação personalizados
  • Construir knowledge base privada acessível a assistentes IA
  • Automatizar fluxos de comunicação com confirmação de segurança

Veredito

Solução sólida e bem-documentada para quem precisa conectar agentes Claude a infraestrutura pessoal. O fluxo de confirmação em duas etapas para emails é um bom padrão de segurança. Requer familiaridade com OAuth, IMAP/SMTP e configuração de webhooks.

README

A tradução para o português deste README ainda está na fila.

Personal MCP Server

A private, single-user MCP (Model Context Protocol) server that gives AI agents access to your email, Slack notifications, and a personal knowledge base ("soul docs"). Written in TypeScript, runs over Streamable HTTP or stdio.

Capabilities at a glance:

  • Search and read Gmail or any IMAP mailbox
  • Send email via Gmail API or custom SMTP (with a prepare→confirm safety flow)
  • Post Slack notifications via incoming webhooks
  • CRUD a personal knowledge base backed by SQLite or Turso/libSQL
  • Configure all credentials at runtime via MCP tools — no .env editing required

Tools

Mail — Gmail

ToolSummary
gmail_search_messagesSearch Gmail with typed filters (from, to, subject, text, label, unread, date range). Returns summaries.
gmail_get_messageFetch a full Gmail message by ID — headers, plain text body, HTML body.

Mail — Custom IMAP / SMTP

ToolSummary
custom_mail_search_messagesSearch a custom IMAP mailbox with the same typed filters.
custom_mail_get_messageFetch a full message from the custom IMAP mailbox by UID.
email_prepare_sendValidate and stage an email draft. Returns a confirmation ID; does not send.
email_confirm_sendSend a previously staged email using its confirmation ID. The two-step flow prevents accidental sends.

Slack

ToolSummary
send_slack_notificationPost a message (plain text or Block Kit blocks) to a configured Slack incoming webhook.

Soul Docs (personal knowledge base)

ToolSummary
get_my_soul_docsSearch docs by full-text query (title, content, source) or filter by tag. Returns newest first.
write_my_soul_docCreate or update a doc. Pass an id to upsert (preserves original created_at); omit to create new. Each doc has a title, body content, tags, an optional source reference, and arbitrary metadata.

Setup (runtime configuration)

When MCP_ENABLE_SETUP_TOOLS=true (the default), these tools let you configure every service at runtime and test connections immediately. All changes are in-memory — they override .env values but reset on restart.

ToolSummary
setup_statusShow which services are configured (no secrets exposed).
setup_databaseSet a Turso/libSQL URL or local file path, then test the connection. Accepts libsql://, file:, or plain paths like /data/db.sqlite.
setup_gmail_oauth_startGenerate a Google OAuth authorization URL. Optionally override client ID, secret, and redirect URI.
setup_gmail_oauth_completeExchange the OAuth authorization code for a refresh token and store it in the runtime config.
setup_custom_mail_imapSet IMAP host, port, credentials, and mailbox — then test the connection.
setup_custom_mail_smtpSet SMTP host, port, credentials, and default from address — then verify the connection.
setup_slack_webhookSet a Slack incoming webhook URL and send a test notification.

Set MCP_ENABLE_SETUP_TOOLS=false to disable all setup tools and use .env-only configuration.


Configuration reference

Every setting can be provided via .env or overridden at runtime by the corresponding setup_* tool.

Runtime

VariableDefaultNotes
MCP_TRANSPORTstreamable-httpstreamable-http, http (alias), or stdio
MCP_PORT3000HTTP listen port
MCP_HOST127.0.0.1Set to 0.0.0.0 for remote access
MCP_BEARER_TOKEN—Optional. When set, requires Authorization: Bearer <token> on all requests
MCP_ALLOWED_ORIGINS*Comma-separated origins or * for all
MCP_ENABLE_SETUP_TOOLStrueSet to false to remove setup_* tools
LOG_LEVELinfodebug, info, warn, or error. Structured JSON logs go to stderr

Database

VariableDefaultNotes
TURSO_DATABASE_URLfile:local.dbfile: for local SQLite, libsql:// for Turso, or a plain path
TURSO_AUTH_TOKEN—Required for Turso remote databases
TURSO_SYNC_URL—Sync endpoint for embedded replicas
TURSO_SYNC_INTERVAL_MS—Sync interval in ms for embedded replicas

Gmail OAuth

VariableRequiredNotes
GOOGLE_CLIENT_IDYesFrom Google Cloud Console
GOOGLE_CLIENT_SECRETYesFrom Google Cloud Console
GOOGLE_REDIRECT_URIYese.g. http://127.0.0.1:3000/oauth/google/callback
GOOGLE_REFRESH_TOKEN—Obtained via OAuth flow; stored at runtime by setup_gmail_oauth_complete
GOOGLE_OAUTH_STATE—Optional CSRF state string

Scopes requested: gmail.readonly, gmail.send.

Custom IMAP

VariableDefaultNotes
CUSTOM_IMAP_HOST—IMAP server hostname
CUSTOM_IMAP_PORT993
CUSTOM_IMAP_SECUREtrueTLS
CUSTOM_IMAP_USER—Usually the full email address
CUSTOM_IMAP_PASSWORD—App password recommended
CUSTOM_IMAP_MAILBOXINBOX

Custom SMTP

VariableDefaultNotes
CUSTOM_SMTP_HOST—SMTP server hostname
CUSTOM_SMTP_PORT587
CUSTOM_SMTP_SECUREfalsetrue for port 465, false for 587 (STARTTLS)
CUSTOM_SMTP_USER—Optional
CUSTOM_SMTP_PASSWORD—Optional
EMAIL_DEFAULT_FROM—Default sender address
EMAIL_CONFIRMATION_TTL_SECONDS86400Expiry for staged-but-unsent emails (24 h default, so drafts survive across sessions)

Slack

VariableNotes
SLACK_WEBHOOK_URLIncoming webhook URL

Getting started

Path A: .env (static config)

npm install
cp .env.example .env
# Edit .env with your credentials
npm run build
npm start                   # HTTP on port 3000
# or: npm run start:stdio   # stdio transport

Path B: setup tools (runtime config)

npm install
npm run build
npm start

Then, from your MCP client, call the setup_* tools in any order:

  1. setup_database — point to your DB (or skip; file:local.db is the default)
  2. setup_gmail_oauth_start → open the URL → setup_gmail_oauth_complete with the code
  3. setup_custom_mail_imap + setup_custom_mail_smtp — configure mail
  4. setup_slack_webhook — configure Slack
  5. setup_status — verify everything is wired up

Endpoints

MethodPathDescription
POST/mcpMCP Streamable HTTP — requires Accept: application/json, text/event-stream
GET/healthzHealth check
GET/oauth/google/startStart Gmail OAuth flow (HTTP mode only)
GET/oauth/google/callbackGmail OAuth callback (HTTP mode only)

Architecture

src/
├── config.ts          Env parsing (Zod), defaults, setConfigValue helper
├── index.ts           Entry point — loads config, creates services, starts transport
├── runtime.ts         Service factory — wires up all services with shared config
├── server.ts          MCP server — registers all tools, conditionally includes setup tools
├── setup-tools.ts     Runtime config tools — mutate config, test connections
├── tools.ts           Core tool handlers — email, Slack, soul docs
├── errors.ts          Custom error classes
├── logger.ts          Structured JSON logging
├── types.ts           Shared TypeScript interfaces
├── transports/
│   ├── http.ts        Streamable HTTP transport + OAuth callback routes
│   └── stdio.ts       Stdio transport
├── services/
│   ├── database.ts    Turso/libSQL client — soul_docs, send_confirmations, audit_log
│   ├── gmail-api.ts   Thin Gmail REST wrapper via google-auth-library + fetch (replaces googleapis)
│   ├── gmail.ts       Gmail service — search, read, send, OAuth
│   ├── custom-mail.ts IMAP (imapflow) + SMTP (nodemailer) — search, read, send
│   ├── email-sender.tsComposite — delegates to Gmail or SMTP based on provider
│   └── slack.ts       Slack incoming webhook via fetch
└── utils/
    ├── email.ts       MIME builder, base64url helpers
    └── mcp.ts         jsonText() response formatter

Key design choices:

  • Shared mutable config — All services hold a reference to the same AppConfig object. Setup tools mutate it directly; lazy services (Gmail, IMAP, SMTP, Slack) pick up changes on the next call. Only DatabaseService needs an explicit reconnect() since it creates the libSQL client eagerly.
  • Audit logging — Every tool call is logged to the audit_log table with success/failure, args (secrets redacted), and a timestamp.
  • Structured logging — Every tool call (with redacted args and duration), email send, and error is also emitted as a JSON log line on stderr, so stdout stays clean for the stdio transport. Set LOG_LEVEL=debug for verbose service-level detail (IMAP/SMTP/Gmail requests, confirmation lifecycle).
  • Two-step email send — email_prepare_send stages a draft (stored in DB with a TTL), email_confirm_send consumes it. Prevents accidental sends and gives the agent a chance to review.
  • OAuth works in both transports — Streamable HTTP mode has dedicated callback routes; stdio mode uses the setup_gmail_oauth_start / setup_gmail_oauth_complete tools where the user copies the code manually.

Database

Three tables are created automatically on startup:

TablePurpose
soul_docsPersonal knowledge base — title, content, tags, source, metadata, timestamps
send_confirmationsStaged email drafts with expiry and single-use tokens
audit_logImmutable record of every tool invocation

Local vs remote

# Local SQLite (relative to working directory)
TURSO_DATABASE_URL=file:local.db

# Local SQLite (absolute — for pods/containers that need persistent state)
TURSO_DATABASE_URL=file:/data/my-server.db

# Remote Turso DB
TURSO_DATABASE_URL=libsql://your-db.turso.io
TURSO_AUTH_TOKEN=your-token

Plain paths passed to setup_database are auto-prefixed with file: — so /data/db.sqlite becomes file:/data/db.sqlite.


Deployment

Docker (GHCR)

Pre-built multi-arch images (linux/amd64, linux/arm64) are published to GitHub Container Registry on every push to main.

# Pull and run
docker run -d --name personal-mcp \
  --env-file .env \
  -p 3000:3000 \
  -v "$(pwd)/data:/app/data" \
  ghcr.io/olamide226/personal-mcp-server:latest

# Or with a specific version
docker run -d --name personal-mcp \
  --env-file .env \
  -p 3000:3000 \
  -v "$(pwd)/data:/app/data" \
  ghcr.io/olamide226/personal-mcp-server:0.1.0

Docker Compose (local build)

docker compose up --build

To pull from GHCR instead of building locally, swap the build: . line in docker-compose.yml for:

image: ghcr.io/olamide226/personal-mcp-server:latest

Bare metal / pod

npm ci --omit=dev
npm run build
MCP_HOST=0.0.0.0 MCP_PORT=3000 TURSO_DATABASE_URL=file:/data/server.db node dist/index.js

For production, set a strong MCP_BEARER_TOKEN and restrict MCP_ALLOWED_ORIGINS to your client origin(s).

Image tags

TagWhen
latestEvery push to main
<full-sha>Every push to main
0.1.0Version tag (e.g. v0.1.0 → 0.1.0)
0.1Major.minor alias (e.g. v0.1.0 → 0.1)
0Major alias (e.g. v0.1.0 → 0)

latest and <full-sha> are published by the docker job in ci.yml on every push to main. The semver tags (0.1.0, 0.1, 0) are published by the docker job in release.yml when a release tag is created — the leading v from the git tag is dropped on the image tags (Docker/OCI convention), so v0.1.0 → 0.1.0. Semantic releases start at v0.1.0.

Note — why the build lives in release.yml: the v* tag is pushed using the default GITHUB_TOKEN, and GitHub does not trigger downstream workflows from GITHUB_TOKEN activity (to prevent loops). So ci.yml's tags: ["v*"] trigger never fires for auto-created tags — the image is built in the same release.yml run that creates the tag instead.

Rebuild an existing tag's image: if a git tag already exists but its image wasn't published (e.g. v0.1.0 predates this workflow), run the Semantic Release workflow manually — Actions → Semantic Release → Run workflow → v0.1.0 — to build and push 0.1.0 / 0.1 / 0 for that tag.

Semantic releases

Merging a PR to main triggers the release.yml workflow which parses conventional commits since the last tag:

Commit prefixVersion bump
feat: ...minor
fix: ..., perf: ...patch
BREAKING CHANGE: ... or feat!: ...major

If any meaningful commits are found, a vX.Y.Z tag is created and the release.yml docker job builds & pushes the matching semver image tags (X.Y.Z, X.Y, X) to GHCR. (The tag push uses GITHUB_TOKEN, so ci.yml is not triggered by it — hence the build runs here.)

Health check

curl http://localhost:3000/healthz
# {"ok":true,"name":"personal-mcp-server","version":"0.1.0"}

Development

npm install
npm run dev          # tsx watch — auto-reload on changes
npm run build        # tsc
npm test             # vitest
npm run lint         # eslint
npm run typecheck    # tsc --noEmit (includes tests/)
Ver o original no GitHub

Bom para

Relacionados