How kenniele/imap_mcp works
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: main.go Server composition · client.go IMAP provider · server.go HTTP and MCP · tools.go Mail tools
Components 26
Entry points
- HTTP and MCP
internal/mcp/server.go - Account CLI
internal/cli/accounts.go - Mail tools
internal/mcp/tools/tools.go - Configuration
internal/config/config.go - Server composition
cmd/server/main.go
Mail services
- Account service
internal/app/accounts.go - Search service
internal/app/search.go - Message service
internal/app/messages.go - Thread service
internal/app/threads.go - Mail domain
internal/domain/message.go
Infrastructure adapters
- IMAP provider
internal/imap/client.go - IMAP search
internal/imap/search.go - IMAP fetch and MIME
internal/imap/fetch.go - IMAP threading
internal/imap/thread.go - Connection pool
internal/imap/pool.go - PostgreSQL accounts
internal/storage/postgres/accounts.go - Metrics and tracing
internal/observability/metrics.go
Identity and security
- Credential encryption
internal/secrets/encryption.go - Bearer and OIDC
internal/auth/middleware.go - OIDC validation
internal/auth/oidc.go - Built-in OAuth
internal/oauth/auth.go - OAuth token store
internal/oauth/store.go - Native OAuth
internal/oauth/native.go
Other components
- MCP client
- Account operator
- IMAP servers
Connections 35
- MCP client → HTTP and MCP: calls tools
README.md - HTTP and MCP → Mail tools: registers tools
internal/mcp/server.go - Mail tools → Account service: invokes services
README.md - Mail tools → Search service: invokes services
README.md - Mail tools → Message service: invokes services
README.md - Mail tools → Thread service: invokes services
README.md - Account service → PostgreSQL accounts: reads and writes
README.md - Account CLI → PostgreSQL accounts: administers accounts
internal/cli/accounts.go - Account CLI → Credential encryption: encrypts credentials
internal/cli/accounts.go - Account CLI → IMAP provider: tests connection
internal/cli/accounts.go - Account service → IMAP provider: tests account
README.md - Search service → IMAP provider: searches mail
README.md - Message service → IMAP provider: gets folders and mail
README.md - Thread service → IMAP provider: gets thread
README.md - IMAP provider → Connection pool: acquires connections
internal/imap/client.go - IMAP provider → IMAP search: runs search
internal/imap/search.go - IMAP search → IMAP fetch and MIME: fetches metadata
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
cmd/server/main.go - Server composition → HTTP and MCP: creates handler
cmd/server/main.go - Server composition → PostgreSQL accounts: opens database
cmd/server/main.go - Server composition → IMAP provider: creates provider
cmd/server/main.go - Server composition → Account service: constructs service
cmd/server/main.go - Server composition → Credential encryption: creates cipher
cmd/server/main.go - HTTP and MCP → Bearer and OIDC: protects endpoints
internal/mcp/server.go - Server composition → OIDC validation: configures OIDC
cmd/server/main.go - Server composition → Built-in OAuth: configures OAuth
cmd/server/main.go - Built-in OAuth → OAuth token store: validates and stores tokens
- HTTP and MCP → Built-in OAuth: serves OAuth routes
internal/mcp/server.go - Built-in OAuth → Native OAuth: supports native clients
- Server composition → Metrics and tracing: creates metrics
cmd/server/main.go - HTTP and MCP → Metrics and tracing: exposes metrics
internal/mcp/server.go - Mail domain → Search service: defines query and results