Chronicle MCP

ChronicleMCP

用于浏览器历史记录的安全、本地第一模型上下文协议（MCP）服务器

](https://pypi.org/project/chronicle-mcp/)   

______________________________________________________________________

目录

1. 快速开始
2. 特性
3. 安装
4. 用法

- CLI命令 - MCP工具 - HTTP API

1. 配置
2. 安全与隐私
3. 支持的浏览器
4. 故障排除
5. 发展
6. 贡献
7. 许可证

______________________________________________________________________

快速开始

# Install
pip install chronicle-mcp

# Run MCP server (stdio mode for AI agents like Claude, Cursor)
chronicle-mcp mcp

# Or start an HTTP server
chronicle-mcp http --port 8080

# Check available browsers
chronicle-mcp list-browsers

______________________________________________________________________

特性

______________________________________________________________________

安装

pip（推荐）

pip install chronicle-mcp

pipx（独立安装）

pipx install chronicle-mcp

码头工人

# Pull the latest image
docker pull ghcr.io/nikolasil/chronicle-mcp:latest

# Run the server
docker run -p 8080:8080 ghcr.io/nikolasil/chronicle-mcp

来源

git clone https://github.com/nikolasil/chronicle-mcp.git
cd chronicle-mcp
pip install -e .

自制（macOS）

brew tap nikolasil/chronicle-mcp
brew install chronicle-mcp

______________________________________________________________________

用法

CLI命令

chronicle-mcp mcp

为AI代理运行MCP服务器。

# Stdio mode (default for AI assistants)
chronicle-mcp mcp

# SSE mode for HTTP clients
chronicle-mcp mcp --sse --port 8080

chronicle-mcp http

启动长时间运行的HTTP REST API服务器。

# Default (foreground, port 8080)
chronicle-mcp http

# Custom port
chronicle-mcp http --port 9000

# Daemon mode
chronicle-mcp http --port 8080 --daemon

# Different browser
chronicle-mcp http --browser firefox

chronicle-mcp status

检查服务器是否正在运行。

chronicle-mcp status --port 8080

chronicle-mcp logs

查看服务器日志。

chronicle-mcp logs --port 8080 --lines 100

chronicle-mcp version

显示版本信息。

chronicle-mcp version

chronicle-mcp list-browsers

列出系统上可用的浏览器。

chronicle-mcp list-browsers
# Output: Available browsers: chrome, edge

chronicle-mcp completion

生成shell完成脚本。

# Bash
chronicle-mcp completion bash >> ~/.bashrc

# Zsh
chronicle-mcp completion zsh >> ~/.zshrc

# Fish
chronicle-mcp completion fish > ~/.config/fish/completions/chronicle-mcp.fish

______________________________________________________________________

MCP工具

search_history

在浏览器历史记录中搜索标题或URL中的关键字。

def search_history(
    query: str,
    limit: int = 5,
    browser: str = "chrome",
    format_type: str = "markdown"
) -> str

例子：

# Markdown output (default)
search_history("python tutorial", limit=10, browser="chrome")

# JSON output
search_history("github", limit=5, format_type="json")

get_recent_history

获取最近N小时的浏览历史记录。

def get_recent_history(
    hours: int = 24,
    limit: int = 20,
    browser: str = "chrome",
    format_type: str = "markdown"
) -> str

例子：

# Last 24 hours
get_recent_history(hours=48, limit=20)

count_visits

统计特定域的总访问量。

def count_visits(
    domain: str,
    browser: str = "chrome"
) -> str

例子：

count_visits("github.com", browser="chrome")
# Output: Visits to 'github.com' in chrome: 42

list_top_domains

获取访问量最大的域名。

def list_top_domains(
    limit: int = 10,
    browser: str = "chrome",
    format_type: str = "markdown"
) -> str

例子：

list_top_domains(limit=20)

search_history_by_date

在日期范围内搜索历史记录。

def search_history_by_date(
    query: str,
    start_date: str,  # ISO format: YYYY-MM-DD
    end_date: str,    # ISO format: YYYY-MM-DD
    limit: int = 10,
    browser: str = "chrome",
    format_type: str = "markdown"
) -> str

例子：

search_history_by_date(
    "python",
    start_date="2024-01-01",
    end_date="2024-12-31",
    limit=20
)

list_available_browsers

返回具有检测到的历史数据库的浏览器列表。

def list_available_browsers() -> str

例子：

list_available_browsers()
# Output: Available browsers: chrome, edge, firefox, brave

delete_history

删除与查询匹配的历史条目。

def delete_history(
    query: str,
    limit: int = 100,
    browser: str = "chrome",
    confirm: bool = False
) -> str

例子：

# Preview what would be deleted (default)
delete_history("spam.com", browser="chrome")
# Actually delete
delete_history("spam.com", browser="chrome", confirm=True)

search_by_domain

在特定域内搜索历史记录。

def search_by_domain(
    domain: str,
    query: str = None,
    limit: int = 20,
    browser: str = "chrome",
    format_type: str = "markdown",
    exclude_domains: list[str] = None
) -> str

例子：

search_by_domain("github.com", browser="chrome")

get_browser_stats

获取浏览器数据库的浏览统计信息。

def get_browser_stats(browser: str = "chrome") -> str

例子：

get_browser_stats(browser="firefox")
# Returns JSON with total visits, domains, date range, etc.

get_most_visited_pages

获取访问量最大的单个页面。

def get_most_visited_pages(
    limit: int = 20,
    browser: str = "chrome",
    format_type: str = "markdown"
) -> str

例子：

get_most_visited_pages(limit=10, browser="chrome")

export_history

将历史记录导出为CSV或JSON格式。

def export_history(
    format_type: str = "csv",
    limit: int = 1000,
    query: str = None,
    browser: str = "chrome"
) -> str

例子：

# Export to CSV
export_history(format_type="csv", limit=1000, browser="chrome")

# Export to JSON
export_history(format_type="json", limit=500, browser="firefox")

search_history_advanced

高级搜索，具有多种选项，包括正则表达式和模糊匹配。

def search_history_advanced(
    query: str,
    limit: int = 20,
    browser: str = "chrome",
    format_type: str = "markdown",
    exclude_domains: list[str] = None,
    sort_by: str = "date",
    use_regex: bool = False,
    use_fuzzy: bool = False,
    fuzzy_threshold: float = 0.6
) -> str

例子：

# Fuzzy search
search_history_advanced("pythn tutorial", use_fuzzy=True, fuzzy_threshold=0.7)

# Regex search
search_history_advanced(r"github\.com/.*/issues/\d+", use_regex=True)

sync_history

在浏览器之间同步历史记录。

def sync_history(
    source_browser: str,
    target_browser: str,
    merge_strategy: str = "latest",
    dry_run: bool = True
) -> str

例子：

# Preview sync
sync_history("chrome", "firefox", dry_run=True)

# Actually sync
sync_history("chrome", "firefox", dry_run=False)

list_available_bookmarks

返回检测到书签的浏览器列表。

def list_available_bookmarks() -> str

例子：

list_available_bookmarks()
# Output: Available browsers with bookmarks: chrome, edge, firefox

list_available_downloads

返回具有检测到的下载历史记录的浏览器列表。

def list_available_downloads() -> str

例子：

list_available_downloads()
# Output: Available browsers with downloads: chrome, edge, firefox

get_bookmarks

从浏览器获取书签。

def get_bookmarks(
    query: str = None,
    limit: int = 50,
    browser: str = "chrome",
    format_type: str = "markdown"
) -> str

例子：

# Get all bookmarks
get_bookmarks(browser="chrome")

# Search bookmarks
get_bookmarks(query="python", browser="firefox")

get_downloads

从浏览器获取下载历史记录。

def get_downloads(
    query: str = None,
    limit: int = 50,
    browser: str = "chrome",
    format_type: str = "markdown"
) -> str

例子：

# Get all downloads
get_downloads(browser="chrome")

# Search downloads
get_downloads(query="pdf", browser="firefox")

______________________________________________________________________

HTTP API

端点

请求/响应示例

POST/api/搜索

curl -X POST http://localhost:8080/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "python tutorial", "limit": 10, "browser": "chrome", "format": "markdown"}'

答复：

{
  "results": [
    {
      "title": "Python Tutorial",
      "url": "https://docs.python.org/3/tutorial/",
      "timestamp": "2024-01-15T10:30:00+00:00"
    }
  ],
  "count": 1
}

GET/健康

curl http://localhost:8080/health

答复：

{
  "status": "healthy",
  "service": "chronicle-mcp",
  "version": "1.1.0",
  "timestamp": "2024-01-15T10:30:00+00:00"
}

______________________________________________________________________

配置

ChronicleMCP可以使用环境变量或配置文件进行配置。

环境变量

配置文件

创建 ~/.config/chronicle-mcp/config.toml:

[default]
browser = "chrome"
limit = 10
format = "markdown"
log_level = "INFO"

______________________________________________________________________

安全与隐私

• 仅限本地： 所有数据都保留在您的机器上
• URL净化： 敏感查询参数将自动删除：

- token, session, key, password, auth, sid, access_token

• 临时文件： 历史记录被复制到临时文件中，这些文件在每次查询后都会被清理
• 未收集数据： 您的浏览数据永远不会发送到任何服务器
• 错误消息： 没有暴露敏感文件路径

______________________________________________________________________

支持的浏览器

ChronicleMCP支持从以下浏览器读取历史记录：

______________________________________________________________________

故障排除

“未找到浏览器历史记录”

• 确保浏览器已安装
• 检查Chrome/Edge当前是否未打开（锁定数据库）
• 跑 chronicle-mcp list-browsers 查看检测到的浏览器

“权限被拒绝”

• 检查浏览器历史数据库上的文件权限
• 在Windows上，查询前请确保浏览器已关闭

空结果

• 尝试更具体的搜索词
• 检查日期范围 search_history_by_date
• 验证浏览器是否有历史数据

性能问题

• 查询大型历史数据库可能需要更长的时间
• 考虑减少 limit 参数

______________________________________________________________________

发展

运行测试

# Run all tests
pytest

# Verbose output
pytest -v

# Specific test file
pytest tests/test_database.py

# Single test
pytest -k test_name

# With coverage
pytest --cov=chronicle_mcp

开发服务器

# Run MCP server (stdio mode)
python -m chronicle_mcp mcp

# Run HTTP server
python -m chronicle_mcp http --port 8080

代码质量

# Linting
ruff check .

# Formatting
ruff format .

# Type checking
mypy chronicle_mcp/

______________________________________________________________________

贡献

欢迎投稿！请阅读我们的 贡献指南 了解详情。

______________________________________________________________________

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

建于❤️ 面向人工智能代理和开发人员