Chatlog MCP Server

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)

pip install chatlog-mcp-server

Option 2: Install from Source

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

Option 3: Install with Development Dependencies

pip install -e ".[dev]"

🚀 Quick Start

1. Install the Package

pip install chatlog-mcp-server

2. Configure MCP Client

Create a mcp-servers.json file:

{
  "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

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

{
  "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

# 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

# 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

# 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:

python -m chatlog_mcp.examples.analyze chatlog.json

🔧 Development

Setup Development Environment

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

Run Tests

pytest

Code Formatting

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 for guidelines.

Development Workflow

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Run tests: pytest
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
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 or open an issue.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Model Context Protocol for the amazing protocol
Claude Code for the MCP client
Anthropic for the support

📞 Support

📧 Email: [email protected]
🐛 Issues: GitHub Issues
📖 Docs: Full Documentation

🗺️ 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