# kenniele/imap_mcp architecture

> Architecture diagram of the GitHub repository kenniele/imap_mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kenniele/imap_mcp
- Repository: https://github.com/kenniele/imap_mcp

## Overview

Multi-account IMAP MCP Server is a read-only Go service for querying mail across enabled accounts, with account administration through a CLI and static Bearer, built-in OAuth, or external OIDC protection. The main workflow is MCP client → authenticated HTTP/MCP endpoint → registered mail tools → application services → IMAP provider → remote mailboxes; results return as MCP responses. Account setup stores encrypted credentials in PostgreSQL. README documents search, folders, recent mail, message retrieval, and threading. OAuth internals and some implementation links are not fully shown, so documented relationships are cited to the README and uncertain connections are omitted.

Main entry points: [`cmd/server/main.go`](https://github.com/kenniele/imap_mcp/blob/main/cmd/server/main.go) (Server composition), [`internal/imap/client.go`](https://github.com/kenniele/imap_mcp/blob/main/internal/imap/client.go) (IMAP provider), [`internal/mcp/server.go`](https://github.com/kenniele/imap_mcp/blob/main/internal/mcp/server.go) (HTTP and MCP), [`internal/mcp/tools/tools.go`](https://github.com/kenniele/imap_mcp/blob/main/internal/mcp/tools/tools.go) (Mail tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_mcp["HTTP and MCP<br/>[server.go]"]
  node_cli["Account CLI<br/>[accounts.go]"]
  node_tools["Mail tools<br/>[tools.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_main["Server composition<br/>[main.go]"]
end

subgraph group_mail["Mail services"]
  node_accounts["Account service<br/>[accounts.go]"]
  node_search["Search service<br/>[search.go]"]
  node_messages["Message service<br/>[messages.go]"]
  node_threads["Thread service<br/>[threads.go]"]
  node_domain["Mail domain<br/>[message.go]"]
end

subgraph group_adapters["Infrastructure adapters"]
  node_imap["IMAP provider<br/>[client.go]"]
  node_imapsearch["IMAP search<br/>[search.go]"]
  node_imapfetch["IMAP fetch and MIME<br/>[fetch.go]"]
  node_imapthread["IMAP threading<br/>[thread.go]"]
  node_pool["Connection pool<br/>[pool.go]"]
  node_postgres[("PostgreSQL accounts<br/>[accounts.go]")]
  node_metrics["Metrics and tracing<br/>[metrics.go]"]
end

subgraph group_security["Identity and security"]
  node_secrets["Credential encryption<br/>[encryption.go]"]
  node_auth["Bearer and OIDC<br/>[middleware.go]"]
  node_oidc["OIDC validation<br/>[oidc.go]"]
  node_oauth["Built-in OAuth<br/>[auth.go]"]
  node_oauthstore[("OAuth token store<br/>[store.go]")]
  node_nativeoauth["Native OAuth<br/>[native.go]"]
end

node_client(("MCP client"))
node_operator(("Account operator"))
node_imapserver{{"IMAP servers"}}

node_client -->|"calls tools"| node_mcp
node_mcp -->|"registers tools"| node_tools
node_tools -->|"invokes services"| node_accounts
node_tools -->|"invokes services"| node_search
node_tools -->|"invokes services"| node_messages
node_tools -->|"invokes services"| node_threads
node_accounts -->|"reads and writes"| node_postgres
node_cli -->|"administers accounts"| node_postgres
node_cli -->|"encrypts credentials"| node_secrets
node_cli -->|"tests connection"| node_imap
node_accounts -->|"tests account"| node_imap
node_search -->|"searches mail"| node_imap
node_messages -->|"gets folders and mail"| node_imap
node_threads -->|"gets thread"| node_imap
node_imap -->|"acquires connections"| node_pool
node_imap -->|"runs search"| node_imapsearch
node_imapsearch -->|"fetches metadata"| node_imapfetch
node_imap -.->|"fetches messages"| node_imapfetch
node_imap -.->|"builds threads"| node_imapthread
node_pool -.->|"connects over IMAP"| node_imapserver
node_main -->|"loads settings"| node_config
node_main -->|"creates handler"| node_mcp
node_main -->|"opens database"| node_postgres
node_main -->|"creates provider"| node_imap
node_main -->|"constructs service"| node_accounts
node_main -->|"creates cipher"| node_secrets
node_mcp -->|"protects endpoints"| node_auth
node_main -->|"configures OIDC"| node_oidc
node_main -->|"configures OAuth"| node_oauth
node_oauth -.->|"validates and stores tokens"| node_oauthstore
node_mcp -->|"serves OAuth routes"| node_oauth
node_oauth -.->|"supports native clients"| node_nativeoauth
node_main -->|"creates metrics"| node_metrics
node_mcp -->|"exposes metrics"| node_metrics
node_domain -.->|"defines query and results"| node_search

click node_mcp "https://github.com/kenniele/imap_mcp/blob/main/internal/mcp/server.go"
click node_cli "https://github.com/kenniele/imap_mcp/blob/main/internal/cli/accounts.go"
click node_tools "https://github.com/kenniele/imap_mcp/blob/main/internal/mcp/tools/tools.go"
click node_accounts "https://github.com/kenniele/imap_mcp/blob/main/internal/app/accounts.go"
click node_search "https://github.com/kenniele/imap_mcp/blob/main/internal/app/search.go"
click node_messages "https://github.com/kenniele/imap_mcp/blob/main/internal/app/messages.go"
click node_threads "https://github.com/kenniele/imap_mcp/blob/main/internal/app/threads.go"
click node_domain "https://github.com/kenniele/imap_mcp/blob/main/internal/domain/message.go"
click node_imap "https://github.com/kenniele/imap_mcp/blob/main/internal/imap/client.go"
click node_imapsearch "https://github.com/kenniele/imap_mcp/blob/main/internal/imap/search.go"
click node_imapfetch "https://github.com/kenniele/imap_mcp/blob/main/internal/imap/fetch.go"
click node_imapthread "https://github.com/kenniele/imap_mcp/blob/main/internal/imap/thread.go"
click node_pool "https://github.com/kenniele/imap_mcp/blob/main/internal/imap/pool.go"
click node_postgres "https://github.com/kenniele/imap_mcp/blob/main/internal/storage/postgres/accounts.go"
click node_config "https://github.com/kenniele/imap_mcp/blob/main/internal/config/config.go"
click node_main "https://github.com/kenniele/imap_mcp/blob/main/cmd/server/main.go"
click node_secrets "https://github.com/kenniele/imap_mcp/blob/main/internal/secrets/encryption.go"
click node_auth "https://github.com/kenniele/imap_mcp/blob/main/internal/auth/middleware.go"
click node_oidc "https://github.com/kenniele/imap_mcp/blob/main/internal/auth/oidc.go"
click node_oauth "https://github.com/kenniele/imap_mcp/blob/main/internal/oauth/auth.go"
click node_oauthstore "https://github.com/kenniele/imap_mcp/blob/main/internal/oauth/store.go"
click node_nativeoauth "https://github.com/kenniele/imap_mcp/blob/main/internal/oauth/native.go"
click node_metrics "https://github.com/kenniele/imap_mcp/blob/main/internal/observability/metrics.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_cli,node_tools,node_config,node_main,node_client toneBlue
class node_accounts,node_search,node_messages,node_threads,node_domain toneAmber
class node_imap,node_imapsearch,node_imapfetch,node_imapthread,node_pool,node_postgres,node_metrics,node_imapserver toneMint
class node_secrets,node_auth,node_oidc,node_oauth,node_oauthstore,node_nativeoauth toneRose
class node_operator toneIndigo
```

## Components

### Entry points

- [HTTP and MCP](https://github.com/kenniele/imap_mcp/blob/main/internal/mcp/server.go): `internal/mcp/server.go`
- [Account CLI](https://github.com/kenniele/imap_mcp/blob/main/internal/cli/accounts.go): `internal/cli/accounts.go`
- [Mail tools](https://github.com/kenniele/imap_mcp/blob/main/internal/mcp/tools/tools.go): `internal/mcp/tools/tools.go`
- [Configuration](https://github.com/kenniele/imap_mcp/blob/main/internal/config/config.go): `internal/config/config.go`
- [Server composition](https://github.com/kenniele/imap_mcp/blob/main/cmd/server/main.go): `cmd/server/main.go`

### Mail services

- [Account service](https://github.com/kenniele/imap_mcp/blob/main/internal/app/accounts.go): `internal/app/accounts.go`
- [Search service](https://github.com/kenniele/imap_mcp/blob/main/internal/app/search.go): `internal/app/search.go`
- [Message service](https://github.com/kenniele/imap_mcp/blob/main/internal/app/messages.go): `internal/app/messages.go`
- [Thread service](https://github.com/kenniele/imap_mcp/blob/main/internal/app/threads.go): `internal/app/threads.go`
- [Mail domain](https://github.com/kenniele/imap_mcp/blob/main/internal/domain/message.go): `internal/domain/message.go`

### Infrastructure adapters

- [IMAP provider](https://github.com/kenniele/imap_mcp/blob/main/internal/imap/client.go): `internal/imap/client.go`
- [IMAP search](https://github.com/kenniele/imap_mcp/blob/main/internal/imap/search.go): `internal/imap/search.go`
- [IMAP fetch and MIME](https://github.com/kenniele/imap_mcp/blob/main/internal/imap/fetch.go): `internal/imap/fetch.go`
- [IMAP threading](https://github.com/kenniele/imap_mcp/blob/main/internal/imap/thread.go): `internal/imap/thread.go`
- [Connection pool](https://github.com/kenniele/imap_mcp/blob/main/internal/imap/pool.go): `internal/imap/pool.go`
- [PostgreSQL accounts](https://github.com/kenniele/imap_mcp/blob/main/internal/storage/postgres/accounts.go): `internal/storage/postgres/accounts.go`
- [Metrics and tracing](https://github.com/kenniele/imap_mcp/blob/main/internal/observability/metrics.go): `internal/observability/metrics.go`

### Identity and security

- [Credential encryption](https://github.com/kenniele/imap_mcp/blob/main/internal/secrets/encryption.go): `internal/secrets/encryption.go`
- [Bearer and OIDC](https://github.com/kenniele/imap_mcp/blob/main/internal/auth/middleware.go): `internal/auth/middleware.go`
- [OIDC validation](https://github.com/kenniele/imap_mcp/blob/main/internal/auth/oidc.go): `internal/auth/oidc.go`
- [Built-in OAuth](https://github.com/kenniele/imap_mcp/blob/main/internal/oauth/auth.go): `internal/oauth/auth.go`
- [OAuth token store](https://github.com/kenniele/imap_mcp/blob/main/internal/oauth/store.go): `internal/oauth/store.go`
- [Native OAuth](https://github.com/kenniele/imap_mcp/blob/main/internal/oauth/native.go): `internal/oauth/native.go`

### Other components

- **MCP client**
- **Account operator**
- **IMAP servers**

## Connections

- MCP client → HTTP and MCP: calls tools (evidence: `README.md`)
- HTTP and MCP → Mail tools: registers tools (evidence: `internal/mcp/server.go`)
- Mail tools → Account service: invokes services (evidence: `README.md`)
- Mail tools → Search service: invokes services (evidence: `README.md`)
- Mail tools → Message service: invokes services (evidence: `README.md`)
- Mail tools → Thread service: invokes services (evidence: `README.md`)
- Account service → PostgreSQL accounts: reads and writes (evidence: `README.md`)
- Account CLI → PostgreSQL accounts: administers accounts (evidence: `internal/cli/accounts.go`)
- Account CLI → Credential encryption: encrypts credentials (evidence: `internal/cli/accounts.go`)
- Account CLI → IMAP provider: tests connection (evidence: `internal/cli/accounts.go`)
- Account service → IMAP provider: tests account (evidence: `README.md`)
- Search service → IMAP provider: searches mail (evidence: `README.md`)
- Message service → IMAP provider: gets folders and mail (evidence: `README.md`)
- Thread service → IMAP provider: gets thread (evidence: `README.md`)
- IMAP provider → Connection pool: acquires connections (evidence: `internal/imap/client.go`)
- IMAP provider → IMAP search: runs search (evidence: `internal/imap/search.go`)
- IMAP search → IMAP fetch and MIME: fetches metadata (evidence: `internal/imap/search.go`)
- IMAP provider → IMAP fetch and MIME: fetches messages
- IMAP provider → IMAP threading: builds threads
- Connection pool → IMAP servers: connects over IMAP
- Server composition → Configuration: loads settings (evidence: `cmd/server/main.go`)
- Server composition → HTTP and MCP: creates handler (evidence: `cmd/server/main.go`)
- Server composition → PostgreSQL accounts: opens database (evidence: `cmd/server/main.go`)
- Server composition → IMAP provider: creates provider (evidence: `cmd/server/main.go`)
- Server composition → Account service: constructs service (evidence: `cmd/server/main.go`)
- Server composition → Credential encryption: creates cipher (evidence: `cmd/server/main.go`)
- HTTP and MCP → Bearer and OIDC: protects endpoints (evidence: `internal/mcp/server.go`)
- Server composition → OIDC validation: configures OIDC (evidence: `cmd/server/main.go`)
- Server composition → Built-in OAuth: configures OAuth (evidence: `cmd/server/main.go`)
- Built-in OAuth → OAuth token store: validates and stores tokens
- HTTP and MCP → Built-in OAuth: serves OAuth routes (evidence: `internal/mcp/server.go`)
- Built-in OAuth → Native OAuth: supports native clients
- Server composition → Metrics and tracing: creates metrics (evidence: `cmd/server/main.go`)
- HTTP and MCP → Metrics and tracing: exposes metrics (evidence: `internal/mcp/server.go`)
- Mail domain → Search service: defines query and results
