# Chatlog MCP Server

[![PyPI version](https://badge.fury.io/py/chatlog-mcp-server.svg)](https://badge.fury.io/py/chatlog-mcp-server)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server for analyzing chat logs from various platforms. This server provides convenient access to chat data through MCP-compatible clients like Claude Code.

## ✨ Features

- 🔍 **4 Core Tools**: List chatrooms, contacts, sessions, and chatlogs
- 📊 **Advanced Analytics**: Message statistics, active members, keyword analysis
- 🔎 **Flexible Search**: Time range, keyword, and sender filtering
- 📈 **Data Export**: JSON, Text, and CSV formats
- 🌐 **Multi-Client Support**: Claude Code, Cursor, VS Code, and more
- 🛠️ **Easy Installation**: pip install and go

## 📦 Installation

### Option 1: Install from PyPI (Recommended)

```bash
pip install chatlog-mcp-server
```

### Option 2: Install from Source

```bash
git clone https://github.com/anthropics/chatlog-mcp-server.git
cd chatlog-mcp-server
pip install -e .
```

### Option 3: Install with Development Dependencies

```bash
pip install -e ".[dev]"
```

## 🚀 Quick Start

### 1. Install the Package

```bash
pip install chatlog-mcp-server
```

### 2. Configure MCP Client

Create a `mcp-servers.json` file:

```json
{
  "mcpServers": {
    "chatlog": {
      "command": "chatlog-mcp",
      "args": [],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```

### 3. Start Using

In Claude Code, simply say:

```
Use the chatlog tool to list chatrooms
```

## 🛠️ Configuration

### Environment Variables

You can configure the server using environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `CHATLOG_API_URL` | HTTP API server URL | `http://127.0.0.1:5030` |
| `CHATLOG_LOG_LEVEL` | Logging level | `info` |

### Command Line Options

```bash
chatlog-mcp --help
```

Options:
- `--api-url URL`: Set custom API URL
- `--log-level LEVEL`: Set logging level (debug, info, warning, error)
- `--version`: Show version and exit

### Example Configuration

```json
{
  "mcpServers": {
    "chatlog": {
      "command": "chatlog-mcp",
      "args": ["--api-url", "http://localhost:5030", "--log-level", "debug"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```

## 📚 Tools

The Chatlog MCP Server provides 4 core tools:

### 1. list_chatrooms

Get a list of chatrooms with optional keyword search.

**Parameters:**
- `keyword` (optional): Search keyword
- `format` (optional): Output format (json/text)

**Example:**
```
Use chatlog to list chatrooms with keyword "AI"
```

### 2. list_contacts

Get a list of contacts with optional keyword search.

**Parameters:**
- `keyword` (optional): Search keyword
- `format` (optional): Output format (json/text)

**Example:**
```
Use chatlog to list contacts with keyword "John"
```

### 3. get_recent_sessions

Get a list of recent sessions.

**Parameters:**
- `format` (optional): Output format (json/text)

**Example:**
```
Use chatlog to get recent sessions
```

### 4. get_chatlog

Get chat logs for a specific time range and chatroom.

**Parameters:**
- `time` (required): Time range (e.g., "2026-01-13" or "2026-01-10~2026-01-13")
- `talker` (required): Chatroom or contact ID
- `sender` (optional): Filter by sender
- `keyword` (optional): Search keyword
- `limit` (optional): Limit number of results
- `offset` (optional): Offset for pagination
- `format` (optional): Output format (json/text/csv)

**Example:**
```
Use chatlog to get chatlogs with these parameters:
{
  "time": "2026-01-13",
  "talker": "123456789@chatroom",
  "format": "json"
}
```

## 📊 Use Cases

### Case 1: Analyze Chatroom Activity

```bash
# Get chat logs for the last 7 days
curl "http://127.0.0.1:5030/api/v1/chatlog?time=2026-01-07~2026-01-13&talker=44156635321@chatroom&format=json"
```

### Case 2: Search for Specific Keywords

```bash
# Find messages containing "AI"
curl "http://127.0.0.1:5030/api/v1/chatlog?time=2026-01-13&talker=44156635321@chatroom&keyword=AI&format=json"
```

### Case 3: Get Top Active Members

```bash
# Export data and analyze with Python
curl "http://127.0.0.1:5030/api/v1/chatlog?time=2026-01-10~2026-01-13&talker=44156635321@chatroom&format=json" > chatlog.json
```

Then use the provided analysis scripts:
```bash
python -m chatlog_mcp.examples.analyze chatlog.json
```

## 🔧 Development

### Setup Development Environment

```bash
git clone https://github.com/anthropics/chatlog-mcp-server.git
cd chatlog-mcp-server
pip install -e ".[dev]"
```

### Run Tests

```bash
pytest
```

### Code Formatting

```bash
black chatlog_mcp/
flake8 chatlog_mcp/
mypy chatlog_mcp/
```

## 📖 Examples

See the `examples/` directory for:

- Sample configurations
- Analysis scripts
- Data export examples
- Integration guides

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Workflow

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes
4. Run tests: `pytest`
5. Commit changes: `git commit -m 'Add amazing feature'`
6. Push to branch: `git push origin feature/amazing-feature`
7. Open a Pull Request

## 📋 Requirements

- Python 3.10 or higher
- HTTP API server running on specified URL
- MCP-compatible client (Claude Code, Cursor, etc.)

## 🐛 Troubleshooting

### Common Issues

**Issue: "Unknown skill: chatlog"**
- Ensure the MCP server is running
- Check that the configuration is correct
- Verify the command path is accessible

**Issue: "Connection refused"**
- Ensure the HTTP API server is running
- Check the API URL in configuration
- Verify network connectivity

**Issue: Chinese characters not displaying correctly**
- Ensure `PYTHONIOENCODING=utf-8` is set
- Use UTF-8 encoding for all files
- Check terminal encoding settings

For more help, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md) or [open an issue](https://github.com/anthropics/chatlog-mcp-server/issues).

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io/) for the amazing protocol
- [Claude Code](https://claude.ai/code) for the MCP client
- [Anthropic](https://anthropic.com) for the support

## 📞 Support

- 📧 Email: support@anthropic.com
- 🐛 Issues: [GitHub Issues](https://github.com/anthropics/chatlog-mcp-server/issues)
- 📖 Docs: [Full Documentation](https://github.com/anthropics/chatlog-mcp-server/blob/main/README.md)

## 🗺️ Roadmap

- [ ] Add support for more chat platforms
- [ ] Real-time message streaming
- [ ] Advanced analytics and visualization
- [ ] Webhook support
- [ ] Plugin system for custom analysis
- [ ] RESTful API for external integrations

---

**Made with ❤️ by the Claude Code team**