Skip to content

justpen-integration-mcp

Gmail + Google APIs integration MCP server for the justpen orchestrator. The read_emails tool retrieves email content or a matching-message count using Gmail service-account delegation and the gmail.readonly scope.

Run the server

The installed package communicates over MCP stdio:

python -m justpen_integration_mcp

From a development checkout, run make setup first, then:

uv run python -m justpen_integration_mcp

Configure the client to use that Python environment. The module entrypoint is the server's existing interface; there is no separate application CLI to install.

Configuration

At startup the server reads JUSTPEN_CONTAINER_HOME (default /justpen_home) and uses integrations.json beneath that directory. The configuration is read when the tool runs. The supported email block is:

{
  "email": {
    "type": "gmail",
    "service_account_json_path": "/path/to/service-account.json",
    "delegated_user": "mailbox@example.com"
  }
}

The service-account file must exist and the delegated user must be a nonempty string. The service account and Google account must already be configured for the requested Gmail delegation. Use an absolute key-file path; ~ is expanded, while other relative paths are resolved from the server's working directory.

INTEGRATION_MCP_LOG_LEVEL controls logging (default INFO). Logs go to stderr. The server reads configuration and does not write it. Keep configuration and service-account credentials outside committed project files.

See the read_emails reference for parameters, returned data, and configuration/API errors.

Development

  • Getting started: install the development tools and understand the automatic Git-hook gates.
  • Claude Code and Codex: activate shared development rules and metadata permissions.
  • PR checklist: branch, commits, tests, docs and merge style.
  • Lint & typing: Ruff and strict Pyright rules.
  • Python API reference: the existing configuration store, response helpers and email registration module.
  • Template updates: update the recorded development baseline while preserving application configuration, licensing and history.

License

Proprietary. Part of the justpen toolkit.