Agentic MCP Solution

A FastAPI + CLI backend that exposes a set of external services — Gmail, Google Docs, Google Sheets, Google Calendar, Google Chat, Postgres, and MongoDB — as MCP-style tools that an LLM (Claude or Gemini) can invoke through a single, consistent interface.

Architecture

• src/core/mcp_base.py / mcp_manager.py — the shared MCP server abstraction and a manager that discovers and dispatches to whichever servers are enabled in config/config.yaml.

• src/core/google_auth.py — OAuth flow for Google Workspace access.

• src/mcp_servers/ — one module per integration (gmail_server.py, gdocs_server.py, gsheets_server.py, gcalendar_server.py, gchat_server.py, postgres_server.py, mongodb_server.py, claude_server.py, gemini_server.py), each implementing the same base interface so new integrations plug in without touching the API or CLI layer.

• src/api/main.py — the FastAPI app exposing these capabilities over HTTP.

• src/cli/main.py — a Click-based CLI for the same capabilities, useful for local testing without standing up the API.

Related MCP server: mcp-google

Verified working

The FastAPI app builds correctly (from src.api.main import app succeeds) and every MCP server module imports cleanly. The CLI runs and exposes:

Commands:
  capabilities  List all available capabilities
  docs          Google Docs operations
  execute       Execute a capability
  gmail         Gmail operations
  health        Check health status of all MCP servers
  task          Execute a complex task

An example end-to-end workflow this architecture supports: inspect Gmail messages → analyze the contents with Claude or Gemini → generate a structured report → create or update a Google Doc with the result, all through the same MCP tool-calling interface.

Getting started

Requires Python 3.13+ (the websockets version this depends on uses typing.Self, which needs 3.11+; the project pins 3.13).

uv sync   # or: pip install -e .
cp .env.example .env   # fill in your API keys

Google Workspace access needs OAuth credentials placed at credentials/credentials.json (gitignored — not something to commit).

uv run agentic-api            # start the FastAPI server
uv run agentic-cli capabilities
uv run agentic-cli health

Status & limitations

gemini_server.py currently uses google.generativeai, which Google has fully deprecated in favor of google.genai — it still works but should be migrated. There's no real test coverage yet (tests/ has the pytest configuration wired up in pyproject.toml but no test bodies). Rate limiting and API-key auth are present in config.yaml but off by default (api_key_required: false) — worth turning on before exposing this beyond local use.

License

MIT — see LICENSE.