mcp-server-personal

Personal-assistant MCP server for personal data. Part of the personal-assistant project; built with FastMCP + Starlette + streamable-http, with per-domain register_tools_* modules.

MCP endpoint: http://localhost:8002/mcp

Tools

Tool	Backend	Config needed
get_calendar_events(start, end) / add_calendar_event(...)	local data/calendar.ics	no
list_emails(n, unread_only) / read_email(id) / label_email(id, label)	Gmail IMAP + app password	IMAP creds
add_contact / mark_contacted / list_contacts_dates()	local SQLite	no

Todos and long-term preference memory live in the main app, not in this server. Email is read + label only — sending is deliberately not an MCP tool; drafts go through the assistant's approval card and a separate gated send path.

Run

cp .env.example .env   # fill IMAP creds if you want email tools
uv sync
uv run src/run.py

Inspect tools:

npx @modelcontextprotocol/inspector
# connect to http://localhost:8002/mcp (streamable-http)
# if ENABLE_AUTH=true, add header: Authorization: Bearer <MCP_AUTH_TOKEN>

Test with the AI agent (LangChain agent over this server's tools):

export OPENAI_API_KEY=sk-...   # or set it in .env
uv run ai_agent.py                                    # example question
uv run ai_agent.py "add lunch with Alex to my calendar this Saturday at noon"

ai_agent.py automatically sends the bearer token from MCP_AUTH_TOKEN when set.

Authentication

The MCP endpoint is protected by a static bearer token (Starlette AuthenticationMiddleware + PersonalAuthBackend in src/auth/auth.py):

• ENABLE_AUTH=true + MCP_AUTH_TOKEN=<random> in .env — clients must send Authorization: Bearer <token>; anything else gets 401.
• ENABLE_AUTH=false — open access (local development).

Generate a token with openssl rand -hex 24.

Observability

• Tracing: OpenTelemetry spans per request (ENABLE_TRACE; TRACE_SPAN_TYPE=local prints to console, otlp exports to a collector).
• Logging: console + rotating file (app.log, 1 MB x 3) via LOG_LEVEL and LOG_PATH. All tool failures are logged with tracebacks — start with grep WARNING app.log / grep ERROR app.log when a tool misbehaves.

Tests

uv run pytest tests -v

Docker

docker build -t mcp-server-personal .
docker run --rm -p 8002:8002 --env-file .env mcp-server-personal

Multi-stage build, non-root user, prod dependencies only; state (calendar.ics, personal.db, logs) lives in /app/data.

CI/CD

• .github/workflows/ci.yaml — on PRs and pushes to main: uv sync + pytest, then a Docker build (no push).
• .github/workflows/cd.yaml — manual (workflow_dispatch): builds and pushes ghcr.io/<owner>/mcp-server-personal:<version> using the built-in GITHUB_TOKEN, with a test/prod environment choice.