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 keywordformat(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 keywordformat(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 IDsender(optional): Filter by senderkeyword(optional): Search keywordlimit(optional): Limit number of resultsoffset(optional): Offset for paginationformat(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-8is 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: support@anthropic.com
- 🐛 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