Timesheet MCP Server

A Model Context Protocol (MCP) server for timesheet management system, built with FastMCP 2.0.

🚀 Quick Start

Installation

Using uvx (recommended):

uvx timesheet-mcp-server

Using pip:

pip install timesheet-mcp-server

Configuration

Set up your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "timesheet": {
      "command": "uvx",
      "args": ["timesheet-mcp-server"],
      "env": {
        "TIMESHEET_API_BASE_URL": "http://127.0.0.1:8080/api",
        "TIMESHEET_API_TOKEN": "your-jwt-token"
      }
    }
  }
}

✨ Features

Time Entry Queries (2)

• Get my time entries with filters
• Get recent time entries

User Queries (3)

• Search users by name
• Get user details
• Get user time entries

Project Queries (7)

• List projects with filters
• Get my projects
• Get project tree structure
• Get project members
• Get project details
• Get project time plan
• List business lines

Reports & Statistics (5)

• Time statistics with grouping
• Time entry reports
• Project time reports
• Working days information
• Time entry warnings

📖 Usage Examples

After setting up, you can use natural language in Claude Desktop:

Please show me my time entries

List all projects

Search for user "John Doe"

Get time statistics for this week

Show me project details for project #123

🔧 Environment Variables

• TIMESHEET_API_BASE_URL - API base URL (required)
• TIMESHEET_API_TOKEN - JWT token for authentication (required)
• MCP_TRANSPORT - Transport method (default: stdio)
• MCP_LOG_LEVEL - Logging level (default: INFO)

🛠️ Development

Clone the repository:

git clone https://github.com/yangyuezheng/ai-emp.git
cd ai-emp/timesheet-mcp-server-v2

Install dependencies:

pip install -r requirements.txt

Run tests:

python test_tools.py

📚 Documentation

• Full Documentation
• Internal Distribution Guide
• Testing Guide

📄 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

• Issues: GitHub Issues
• Documentation: GitHub Docs

🙏 Acknowledgments

• FastMCP - MCP framework
• Model Context Protocol - Protocol specification
• Claude - AI assistant

---

Version: 2.0.0 Status: Production Ready ✅