Gmail / IMAP
  └─► Bichon (Docker, localhost:15630)
        local Tantivy FTS + compressed EML store
        └─► bichon-mcp  (this repo, stdio MCP server)
              └─► Claude Code / Claude Desktop

git clone https://github.com/pras-labs/bichon-mcp
cd bichon-mcp
uv venv
uv pip install -e .

docker run -d --name bichon -p 15630:15630 rustmailer/bichon:latest

curl -s -X POST http://localhost:15630/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin@bichon"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])"

cp .mcp.json.example .mcp.json

{
  "mcpServers": {
    "bichon-email": {
      "command": ".venv/bin/python",
      "args": ["-m", "bichon_mcp"],
      "env": {
        "BICHON_BASE_URL": "http://localhost:15630",
        "BICHON_ACCESS_TOKEN": "<your-token>"
      }
    }
  }
}

{
  "mcpServers": {
    "bichon-email": {
      "command": "/path/to/bichon-mcp/.venv/bin/python",
      "args": ["-m", "bichon_mcp"],
      "env": {
        "BICHON_BASE_URL": "http://localhost:15630",
        "BICHON_ACCESS_TOKEN": "<your-token>"
      }
    }
  }
}

Returns: [{id, email}]

account_id*  integer  From list_accounts

Returns: [{id, name, total, unseen}]

account_id*  integer  From list_accounts
mailbox_id*  integer  From list_mailboxes

Returns:
  total_emails    integer   Exact count from Bichon
  sampled         integer   Emails analysed (up to 200 most recent)
  top_senders     [{sender, count}]
  top_subjects    [{subject, count}]
  oldest_in_sample / newest_in_sample  integer (unix ms)
  cached          boolean

query*       string   Full-text search term (max 500 chars)
date_from    string   ISO date YYYY-MM-DD (inclusive)
date_to      string   ISO date YYYY-MM-DD (inclusive)
sender       string   Filter by sender address (max 254 chars)
account_id   integer  Scope to one account
mailbox_id   integer  Scope to one mailbox folder
limit        integer  Max results, default 20, max 50

Returns: [{id, account_id, subject, from, to, date, preview, thread_id, has_attachments}]

account_id*   integer  From search_emails result
envelope_id*  string   UUID from search_emails result

Returns: {account_id, envelope_id, body, attachment_count}

subject_contains  string   Filter by subject text (max 500 chars)
sender            string   Filter by sender (max 254 chars)
limit             integer  Max threads to return, default 10

Returns: [{thread_id, account_id, subject, latest_from, latest_date, count}]

email_address*  string  Valid email address (max 254 chars)

Returns: {email, count, first_seen, last_seen, top_subjects}

User: "Summarise my email activity for the past month."

Claude:
  1. list_accounts()               → finds account IDs
  2. list_mailboxes(account_id)    → finds INBOX mailbox_id
  3. get_mailbox_stats(...)        → top senders, subjects, total count
  4. search_emails(query="", date_from="2026-04-20", ...)  → recent emails
  5. get_email(...) × N            → reads relevant messages
  → synthesises a summary

# Install in editable mode
uv pip install -e .

# Verify MCP tools are registered (no Bichon needed)
python3 -c "
import subprocess, json, os, threading, queue, time
proc = subprocess.Popen(['.venv/bin/python', '-m', 'bichon_mcp'],
    stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
    env={**os.environ, 'BICHON_BASE_URL':'http://localhost:15630','BICHON_ACCESS_TOKEN':'test'},
    text=True, bufsize=1)
q = queue.Queue()
threading.Thread(target=lambda: [q.put(l.strip()) for l in proc.stdout], daemon=True).start()
for msg in [
    {'jsonrpc':'2.0','id':1,'method':'initialize','params':{'protocolVersion':'2024-11-05','capabilities':{},'clientInfo':{'name':'t','version':'0'}}},
    {'jsonrpc':'2.0','method':'notifications/initialized','params':{}},
    {'jsonrpc':'2.0','id':2,'method':'tools/list','params':{}},
]:
    proc.stdin.write(json.dumps(msg)+'\n')
proc.stdin.flush()
deadline = time.time()+10
while time.time()<deadline:
    try:
        line = q.get(timeout=1)
        obj = json.loads(line)
        if obj.get('id')==2:
            print([t['name'] for t in obj['result']['tools']])
            break
    except: pass
proc.terminate()
"
# Expected: ['list_accounts', 'list_mailboxes', 'get_mailbox_stats', 'search_emails', 'get_email', 'list_threads', 'get_sender_summary']