Content
# Ticket Management System - MCP/Firebase Integration
This project provides an MCP server that integrates Claude for Desktop (MCP client) with Firebase Firestore to implement a ticket management system.
## Feature Overview
- Create, update, and add history to tickets
- Retrieve ticket list (with filtering and sorting features)
- View ticket details
- Retrieve master data (users, accounts, categories, etc.)
## System Configuration
- **Frontend**: Claude for Desktop (MCP client)
- **Backend**: Python MCP Server (Model Context Protocol)
- **Database**: Google Cloud Firestore
## Prerequisites
- Python 3.10 or higher
- firebase-admin
- mcp[cli] 1.8.0 or higher
- Access permissions to Google Cloud Firestore
- Claude for Desktop
- uv command-line tool (used in Claude for Desktop settings)
## Environment Setup Steps
### 1. Set Up GCP Project
1. Access [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new GCP project or select an existing project
3. Check that billing is enabled in the "Billing" section and enable it if necessary
### 2. Configure Firestore
1. Enable the Cloud Firestore API
```
Google Cloud Console > APIs & Services > Library > Cloud Firestore API
```
2. Create a Firestore database
- Mode: Select **Native mode**
- Location: Choose the database region (e.g., `asia-northeast1` (Tokyo))
- Database ID: `mcp-status-test` (used for this project)
3. Set security rules
- Navigate to the "Rules" tab in Firestore
- Example development rules (**do not use in production**):
```
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /{document=**} {
allow read, write: if true; // Development: Anyone can read and write
}
}
}
```
### 3. Obtain Service Account and Secret Key
1. Create a service account
```
Google Cloud Console > IAM & Admin > Service Accounts > Create Service Account
```
2. Assign roles
- Select the "Cloud Datastore User" role
- Alternatively, assign the "Firestore Data Viewer" and "Firestore Data Editor" roles
3. Download the secret key (JSON)
- In the service account's "Keys" tab, click "Create New Key"
- Download the JSON key and rename it to `firebase-credentials.json`
**Note: Do not include the secret key file in your Git repository.**
### 4. Set Up Local Development Environment
1. Clone the repository
```bash
git clone https://github.com/Masa1984a/ticket-management-mcp.git
cd ticket-management-mcp
```
2. Create and activate a Python virtual environment
```bash
# Navigate to the project directory
cd project_directory_path
# Create a Python virtual environment
python -m venv .venv
# Activate the virtual environment (Windows/PowerShell)
.\.venv\Scripts\Activate.ps1
# (For Command Prompt)
# .\.venv\Scripts\activate.bat
# (For Linux/Mac)
# source .venv/bin/activate
```
3. Place the secret key file
- Place the downloaded secret key JSON file in the project root with the name `firebase-credentials.json`
4. Install dependencies
```bash
# Upgrade pip to the latest version
python -m pip install --upgrade pip
# Install dependencies
pip install -r requirements.txt
```
5. Set environment variables
Instead of placing the secret key file in the project root, you can set environment variables:
```bash
# Windows/PowerShell
$env:GOOGLE_APPLICATION_CREDENTIALS = "C:\path\to\your\firebase-credentials.json"
# Linux/Mac
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/firebase-credentials.json"
```
6. Configure Claude for Desktop
Edit the Claude for Desktop configuration file `claude_desktop_config.json`:
```json
{
"mcpServers": {
"TicketManagementSystem": {
"command": "uv",
"args": [
"--directory", "project_directory_path",
"run",
"main.py"
]
}
}
}
```
**Note**: Replace `project_directory_path` with the actual project path. On Windows, you need to escape backslashes in the path. Example: `C:\\Users\\username\\projects\\ticket-system`
### 5. Prepare Sample Data
1. First, create basic master data:
```bash
python ./firestore/firebase_init.py
```
2. Next, create additional demo data:
```bash
python ./firestore/demo_data_generator.py
```
This command will create the following data:
- Additional users (e.g., "Shin Ue" as an administrator)
- Additional categories (e.g., UX improvement requests)
- Chat/LLM reception channels
- Approximately 40 demo sample tickets (a balanced combination of categories and statuses)
- Sample tickets related to the search functionality
3. Check the inserted data:
```bash
python ./firestore/check_firestore_data.py --tickets --search
```
4. If data creation fails, run the following scripts to troubleshoot:
- test_firebase.py: Check connection to Firestore
- test_firestore_write.py: Check data creation in Firestore
## How to Run
### Local Testing
Run the Python MCP server directly:
```bash
python main.py
```
Or use MCP Inspector:
```bash
mcp dev main.py
```
- MCP Inspector is an interactive debugging tool for MCP Server developers. It provides a visual interface for developers to test and validate custom tools and servers that integrate with AI applications (Claude for Desktop, Cursor, Roo Code, etc.).
### Registering with Claude for Desktop
Register the MCP server with Claude for Desktop:
Copy `./claude_desktop_configuration/claude_desktop_configuration.json` to the appropriate folder for Claude for Desktop.
After this, launch Claude for Desktop.
## Usage (Claude for Desktop)
You can operate the system with natural language commands such as:
- "Create a new ticket"
- "Show the list of tickets assigned to Yamada"
- "Display details of ticket TCK-0001"
- "Update the status of ticket TCK-0001 to 'In Progress'"
- "Add a comment to ticket TCK-0001"
If an index error occurs, please build the index from the URL mentioned in the error message.
## Developer Information
### Project Structure
- `main.py`: Implementation of the MCP server
- `requirements.txt`: List of dependencies
- `README.md`: Project description
### Firestore Schema
This system uses the following collections:
- `users`: User information (assignees, requesters)
- `accounts`: Account information
- `categories`: Category information
- `categoryDetails`: Category detail information
- `statuses`: Status information
- `requestChannels`: Reception channel information
- `responseCategories`: Response classification information
- `tickets`: Ticket information
- `counters`: Automatic numbering counters
### MCP Server API
This MCP server provides the following tools and resources:
**Tools:**
- `get_ticket_list`: Retrieve ticket list
- `get_ticket_detail`: Retrieve ticket details
- `create_ticket`: Create a ticket
- `update_ticket`: Update a ticket
- `add_ticket_history`: Add history to a ticket
- `get_users`: Retrieve user list
- `get_accounts`: Retrieve account list
- `get_categories`: Retrieve category list
- `get_category_details`: Retrieve category details list
- `get_statuses`: Retrieve status list
- `get_request_channels`: Retrieve reception channel list
## License
This project is provided under the MIT License. Please refer to the LICENSE file for details.
