eight-mcp-community 0.2.0

Unofficial Python client and stdio MCP server for Eight person search workflows.

eight-mcp-community

Unofficial Python client and stdio MCP server for Eight person-search workflows.

[!WARNING] This project is unofficial and not affiliated with Eight or Sansan. It uses private/internal web endpoints that can change without notice. Keep cookies, credentials, and raw contact data out of GitHub, logs, issues, prompts, and public reports.

Design

This package follows the same idea as note-mcp-community, but the core is Python:

• PyPI/project name: eight-mcp-community
• Python import package: eight
• CLI commands: eight-mcp-community and eight-mcp
• MCP server: stdio, suitable for local/private agent use

The core client is reusable without an LLM:

from eight import EightClient

client = EightClient.from_default_config()
result = client.search_person("鈴木太郎 東京商事")
print(result.to_safe_dict())

The MCP server is a thin wrapper over the same EightClient.

Install / run

Local development:

uv sync --dev
uv run eight-mcp-community --help
uv run eight-mcp-community serve

Run directly without installing permanently:

uvx eight-mcp-community serve

If Eight returns Cloudflare-style 403 responses with valid cookies, use the optional curl_cffi transport. It impersonates Chrome for the normal CLI/MCP path and does not require Playwright:

uvx --from 'eight-mcp-community[cloudflare]' eight-mcp-community serve

If you install with python -m pip install --user eight-mcp-community, the command may be placed under ~/.local/bin, which is not always on PATH. Either add that directory to PATH, use the absolute path, or run the module form:

python -m eight serve
~/.local/bin/eight-mcp-community serve

MCP client configuration:

{
  "mcpServers": {
    "eight": {
      "command": "uvx",
      "args": ["eight-mcp-community", "serve"]
    }
  }
}

Codex MCP examples:

# PATH-based
codex mcp add eight -- eight-mcp-community serve

# pip --user / absolute-path style
codex mcp add eight -- /Users/you/.local/bin/eight-mcp-community serve

# module form, useful when the command is not on PATH
codex mcp add eight -- python3 -m eight serve

# Cloudflare-resistant transport via uvx
codex mcp add eight -- uvx --from 'eight-mcp-community[cloudflare]' eight-mcp-community serve

After package upgrades, optional dependency changes, authentication changes, or MCP configuration edits, restart Codex / your MCP client or otherwise restart the MCP server process. Already-running MCP servers keep using the old Python process.

Recommended post-install message for agents:

Eight MCP registration is installed. Authentication is intentionally simple:
1. Check current state: /Users/you/.local/bin/eight-mcp-community auth-status
2. If no cookie is configured, log in with Playwright. Recommended install for Eight login reliability: python -m pip install --user 'eight-mcp-community[browser,cloudflare]' && python -m playwright install chromium
3. If you already have a trusted Cookie header, save it directly: /Users/you/.local/bin/eight-mcp-community set-cookie '<COOKIE_HEADER>'
If a known-good cookie returns 403, use/install eight-mcp-community[cloudflare]. Restart Codex or the MCP client after package/auth/config changes.

Local development MCP config:

{
  "mcpServers": {
    "eight": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/eight-mcp-community",
        "run",
        "eight-mcp-community",
        "serve"
      ]
    }
  }
}

Authentication

The authentication surface is intentionally small:

1. auth-status checks whether a Cookie header is configured and whether it can currently access Eight.
2. auth-login uses Playwright for an interactive browser login, captures 8card.net cookies, and saves them.
3. set-cookie saves a trusted Cookie header supplied from outside the MCP flow.

Unless you provide a Cookie header via set-cookie or EIGHT_COOKIE, logging in requires Playwright. For Eight, installing both browser and cloudflare extras is recommended because the final cookie verification may need Chrome-like HTTP transport:

python -m pip install --user 'eight-mcp-community[browser,cloudflare]'
python -m playwright install chromium
~/.local/bin/eight-mcp-community auth-login

The MCP eight_auth_login tool runs the CLI login flow in a subprocess so Playwright does not collide with the MCP server's asyncio loop.

If Playwright's browser binary is missing, install it once on the same machine/user account:

python -m playwright install chromium

Create or overwrite the config file from a trusted Cookie header:

~/.local/bin/eight-mcp-community set-cookie '<COOKIE_HEADER>'
~/.local/bin/eight-mcp-community auth-status

Supported credential lookup order:

1. EIGHT_COOKIE — externally supplied Cookie header
2. EIGHT_MCP_COMMUNITY_CONFIG — path to config JSON with a cookie field
3. Default config file: ~/.config/eight-mcp-community/config.json

If auth-login times out after the browser reached /myhome, the cookie was probably captured but the verification HTTP request failed. The timeout message includes the last non-secret diagnostic (reason, HTTP status, final URL, and Cloudflare-like signal). Use the [cloudflare] extra and restart the MCP client:

python -m pip install --user 'eight-mcp-community[cloudflare]'

CLI

eight-mcp-community auth-status
eight-mcp-community auth-login
eight-mcp-community set-cookie 'Cookie header'
eight-mcp-community search '鈴木'
eight-mcp-community search '鈴木' --source all
eight-mcp-community fetch-person '<ID_FROM_SEARCH>'
eight-mcp-community serve

All command output is JSON except --help.

MCP tools

Authentication tools:

• eight_auth_status — check whether auth is configured and whether the current Cookie can access Eight
• eight_auth_login — open a Playwright browser login flow, capture cookies, and save them through eight_set_cookie
• eight_set_cookie — store a trusted Cookie header in the local MCP config file

Search tools:

• eight_search_person — search people and return minimal result fields plus fetchable ids. By default it searches only registered/exchanged cards. Set source: "all" to also search public Eight network results. Public network people are returned in network; public network company hits are returned separately in network_companies.
• eight_fetch_person — fetch detailed fields for an id returned by eight_search_person. Registered-card ids can include contact fields such as email and phone numbers; public-network ids return public profile-style fields when available.

Search results are intentionally minimal and LLM-safe: id, source, name, company, department, title, updated date, confidence/source bucket, and when available matched_fields / match_excerpt so users can understand why a result matched. Raw HTML, raw JSON, cookies, tokens, email addresses, phone numbers, and bulk exports are not returned by search. Use eight_fetch_person only when detailed contact/profile fields are actually needed.

Privacy and safety

• Do not use this project for bulk contact export or contact-list harvesting.
• Do not commit cookies, config files, raw API dumps, screenshots, or credentials.
• Treat registered business-card results as private context; cite public sources for public-facing reports.
• Eight business-card data can be stale. Corroborate current affiliation/title with public sources when accuracy matters.

Development

uv sync --dev
uv run ruff check .
uv run pytest

Manual MCP smoke test:

printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke-test","version":"0.0.0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| timeout 5s uv run eight-mcp-community serve