Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@bichon-mcp search my inbox for receipts from last month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server that wraps the Bichon email archiver REST API, letting an AI agent (Claude Code, Claude Desktop) search and read locally-archived emails — without ever touching Gmail or IMAP credentials directly.
Gmail / IMAP
└─► Bichon (Docker, localhost:15630)
local Tantivy FTS + compressed EML store
└─► bichon-mcp (this repo, stdio MCP server)
└─► Claude Code / Claude DesktopAfter the initial IMAP sync, the AI only ever calls localhost:15630. No external auth is granted to the AI.
Related MCP server: gmail-research-mcp
Python 3.11+
uv (recommended) or pip
Bichon running locally — see Bichon quickstart
git clone https://github.com/pras-labs/bichon-mcp
cd bichon-mcp
uv venv
uv pip install -e .Start Bichon (Docker):
docker run -d --name bichon -p 15630:15630 rustmailer/bichon:latestThen get a token:
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'])"For a long-lived token, create one in the Bichon WebUI under Settings → Access Tokens.
Copy .mcp.json.example to .mcp.json and fill in the 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>"
}
}
}
}
.mcp.jsonis gitignored — your token will not be committed.
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
{
"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>"
}
}
}
}All configuration is via environment variables:
Variable | Default | Description |
|
| Bichon instance URL |
| (required) | Bearer token for Bichon API |
|
| Mailbox stats cache TTL in seconds. |
|
| HTTP request timeout in seconds |
list_accounts()List all email accounts configured in Bichon.
Returns: [{id, email}]Example prompt: "What email accounts are set up?"
list_mailboxes(account_id)List mailbox folders for an account (INBOX, Sent, Drafts, etc.).
account_id* integer From list_accounts
Returns: [{id, name, total, unseen}]Example prompt: "Show me all mailboxes for my account."
get_mailbox_stats(account_id, mailbox_id)Per-mailbox statistics: total email count, top senders, top subjects by frequency. Results are cached (default 5 min, configurable via BICHON_STATS_CACHE_TTL).
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 booleanExample prompt: "Give me stats for my INBOX — who emails me most?"
search_emails(query, ...)Full-text search across archived emails. Returns summaries only — no body text.
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}]Example prompts:
"Search for emails about invoices from last month."
"Find emails from notifications@github.com in my INBOX."
get_email(account_id, envelope_id)Fetch the full plain-text content of one email. HTML is stripped. Body is truncated at ~4000 tokens.
account_id* integer From search_emails result
envelope_id* string UUID from search_emails result
Returns: {account_id, envelope_id, body, attachment_count}Example prompt: "Show me the full content of that invoice email."
list_threads(subject_contains?, sender?, limit?)Group search results by thread_id to show conversation threads.
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}]Example prompt: "Show me all threads from GitHub notifications."
get_sender_summary(email_address)Aggregate stats for a sender: total email count, date range, top subjects.
email_address* string Valid email address (max 254 chars)
Returns: {email, count, first_seen, last_seen, top_subjects}Example prompt: "How many emails have I received from packt@mail.packtpub.com and what are they about?"
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 summaryThe access token is read from BICHON_ACCESS_TOKEN at startup — never hardcode it in source files.
.mcp.json is gitignored to prevent accidental token commits.
envelope_id values are validated as UUIDs before use in API paths.
All string inputs have length limits; integer IDs must be positive.
API error responses are not forwarded to the AI (only the HTTP status code is).
Email bodies are passed directly to Claude. Malicious emails may contain text designed to manipulate AI behaviour — a known limitation of any email-reading AI tool.
# 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']AGPL-3.0. If you distribute this software, the source must remain open.
Get full plain-text content of an email. account_id and envelope_id come from search_emails results. HTML is stripped. Body is truncated at ~4000 tokens.
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | Yes | ||
| envelope_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses key behaviors: HTML is stripped, body truncated at ~4000 tokens. This is good for a simple tool, though it does not cover error cases or authentication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. Purpose is front-loaded; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters and no output schema, the description covers what is returned (plain-text, truncated) and the source of parameters. It omits response format details but is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It mentions that parameters come from 'search_emails', adding context, but does not explain their format or constraints beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get full plain-text content of an email', identifying the verb (get) and resource (email). It distinguishes from sibling tools like 'search_emails' by noting that parameters come from it, and from list tools by focusing on a single email.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It specifies that 'account_id and envelope_id come from search_emails results', indicating the prerequisite step. It does not explicitly list when not to use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stats for a specific mailbox folder: total count, top senders, top subjects by frequency. Use list_mailboxes to find mailbox_id. Samples up to 200 most recent emails. Results cached for BICHON_STATS_CACHE_TTL seconds (default 300). Set to 0 to disable.
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | Yes | ||
| mailbox_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses caching behavior and sampling (up to 200 recent emails), but does not explicitly state read-only nature or side effects. With no annotations, the description partially fulfills this need.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each adding value—no filler, well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, caching, sampling, and a parameter hint, but lacks output format specifics since no output schema is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%; description clarifies mailbox_id via mention of list_mailboxes, but does not explain account_id, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides stats (total count, top senders, top subjects) for a specific mailbox folder, distinguishing it from sibling tools like list_mailboxes and get_email.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Advises using list_mailboxes to find mailbox_id, which is helpful but does not explicitly mention when not to use this tool or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregate stats for a sender: total count, date range, top subjects.
| Name | Required | Description | Default |
|---|---|---|---|
| email_address | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions the output (stats) but does not state whether the tool is read-only, requires authentication, or has any side effects. This lack of behavioral context is a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the tool's function, though it could be slightly expanded for completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no output schema), the description covers basic stats but omits details like output format or pagination. It is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, email_address, is well-named but lacks schema description (0% coverage). The description adds minimal value by implying it identifies the sender. It partially compensates for the missing schema descriptions but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: aggregating statistics for a sender, including total count, date range, and top subjects. It distinguishes itself from sibling tools like get_email and get_mailbox_stats by focusing on sender-level aggregates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives, nor does it specify prerequisites or context. A brief sentence indicating appropriate usage would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all email accounts configured in Bichon. Returns account id and email address.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description conveys a safe read-only action. It lists all accounts without side effects. Could add context on pagination or filtering, but adequate for a simple list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action and result, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and an output schema, the description is complete. It explains scope and return fields, sufficient for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has no parameters, so coverage is 100%. Description adds no param info, but none needed. Baseline 4 due to no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all email accounts in Bichon and returns account id and email address. It distinguishes from siblings that handle emails, mailboxes, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing accounts but provides no explicit guidance on when to use it vs alternatives like list_mailboxes or get_email. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List mailbox folders for an account (INBOX, Sent, etc.). Use list_accounts to find account_id. Returns id, name, total message count, unseen count.
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the return fields (id, name, total message count, unseen count) which adds value beyond the output schema. However, with no annotations, it fails to disclose potential side effects, permissions needed, or reliability considerations (e.g., pagination, real-time vs cached data).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: two sentences with no extraneous words. The first sentence delivers the core purpose, and the second covers prerequisite and return info. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, output schema present), the description covers the essential aspects: action, required input derivation, and return content. It lacks details like error handling or performance notes, but for a straightforward list tool, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for the account_id parameter. The description compensates by explaining that account_id comes from list_accounts, providing essential context for the agent to select the correct parameter value. This significantly adds meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists mailbox folders (INBOX, Sent, etc.) and what it returns. It is specific about the action and resource, but does not explicitly differentiate from sibling tools like get_email or search_emails, which limits clarity in distinguishing use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite hint ('Use list_accounts to find account_id') which guides the user on required prior action. However, it does not specify when to use this tool versus alternatives (e.g., get_mailbox_stats) or when not to use it, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List email threads by grouping search results on thread_id. Returns one entry per thread with message count and latest date.
| Name | Required | Description | Default |
|---|---|---|---|
| subject_contains | No | ||
| sender | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description indicates this is a read operation (listing) and specifies the return format (per thread with count and date). It does not mention destructive actions or auth needs, but the behavior is clear from the context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences and no fluff. It could be slightly improved by front-loading key details, but it is well-structured for a short description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the return format (message count, latest date) and basic purpose, but lacks details on parameter behavior (e.g., whether subject_contains is partial match) and pagination. Given the 3 optional parameters and existing output schema, it is adequate but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention any of the three parameters (subject_contains, sender, limit) or explain how they affect results. With 0% schema description coverage, the description fails to compensate, leaving parameter semantics unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists email threads by grouping on thread_id, returning one entry per thread with message count and latest date. This distinguishes it from sibling tools like search_emails (which returns individual emails) and get_email (specific email).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it is for listing threads, but does not explicitly state when to use it over alternatives like search_emails or get_email. No guidance on prerequisites or comparison to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search emails by full-text query, date range, sender, and/or mailbox folder. Returns summaries only (no body). Use get_email for full content. date_from/date_to accept ISO dates (YYYY-MM-DD). Max limit is 50. Use list_accounts + list_mailboxes to find account_id and mailbox_id.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| date_from | No | ||
| date_to | No | ||
| sender | No | ||
| account_id | No | ||
| mailbox_id | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: returns summaries only, accepts date ranges in ISO format, max limit 50. Lacks info on pagination or sorting, but given the read-only nature of a search, the essential behaviors are covered. With no annotations, this description provides adequate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each packed with useful information. No redundant words. The first sentence states the purpose and filters, the second details output and alternatives. Ideal conciseness without sacrificing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers most important aspects: purpose, parameters, output type, and preparatory calls. Could mention pagination or sorting behavior, but the presence of an output schema mitigates omission of return field details. Considering tool complexity, it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must carry the full semantic load. It explains the query is full-text search, dates are ISO format, limit max is 50, and how to obtain account_id and mailbox_id. This adds essential meaning beyond the bare schema properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches emails with specific filters (query, date range, sender, mailbox folder). It distinguishes itself by noting it returns summaries only, and directs to get_email for full content. This differentiates it from siblings effectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool (for summaries) and when not (for full content, use get_email). Provides instructions for obtaining required IDs via list_accounts and list_mailboxes. Specifies date format and maximum limit. This gives clear guidance for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0get_emailget_mailbox_statsget_sender_summarylist_accountslist_mailboxeslist_threadssearch_emailsEach tool targets a distinct purpose: listing accounts, mailboxes, threads; searching emails; retrieving full email content; and obtaining statistics on a mailbox or sender. No overlapping functionality.
All tools follow a consistent verb_noun pattern using snake_case: 'list_' for enumerations, 'get_' for retrievals, and 'search_' for searching. No mixing of conventions.
With 7 tools, the set is well-scoped for a read-only email retrieval and statistics server. Each tool covers a necessary operation without redundancy or deficiency.
The tool surface covers the full lifecycle for read-only email access: listing accounts and mailboxes, searching, retrieving full content, and aggregating stats. No obvious gaps for the stated purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Email safety MCP server. Detects phishing, prompt injection, CEO fraud for AI agents.
Hosted email MCP for AI agents with inboxes, send/receive, memory, recovery, and credits.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/pras-labs/bichon-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
