Jira Weekly Reporter MCP Server

<!-- Adjust if using a different license -->

This project provides a FastMCP server that connects to your Jira instance (Cloud or Server/Data Center) to generate weekly reports based on issue activity. It leverages the pycontribs-jira library for Jira interaction and can optionally use the connected client's Large Language Model (LLM) for summarizing the generated report.

✨ Features

• Jira Connection: Securely connects to Jira using API tokens stored in a .env file.
• MCP Tool: Exposes a generate_jira_report tool accessible via the Model Context Protocol.
• Flexible Reporting:
  • Defaults to reporting issues updated in the last 7 days.
  • Allows specifying a custom JQL query.
  • Can filter reports by a specific Jira project key.
  • Limits the number of results returned (configurable).
• (Optional) LLM Summarization: Can use the client's LLM (via ctx.sample()) to provide a concise summary of the report.
• Asynchronous Handling: Properly handles synchronous Jira library calls within the asynchronous FastMCP server using asyncio.to_thread.

📋 Prerequisites

• Python 3.10 or later.
• uv (recommended) or pip for package management.
• Access to a Jira instance (Cloud, Server, or Data Center).
• A Jira API Token (Personal Access Token for Server/DC).
• FastMCP CLI installed and available in your system's PATH.

⚙️ Setup

1. Clone the Repository (if applicable):

   git clone https://github.com/Jongryong/jira_reporter.git
   cd jira_reporter
   

2. Install Dependencies: We recommend using uv:

   uv pip install fastmcp "jira[cli]" python-dotenv httpx anyio
   

   Alternatively, use pip:

   pip install fastmcp "jira[cli]" python-dotenv httpx anyio
   

3. Create .env File: Create a file named .env in the same directory as jira_reporter_server.py. Add your Jira connection details:

   # .env
   JIRA_URL=https://your-domain.atlassian.net  # Your Jira Cloud URL or Self-Hosted URL
   JIRA_USERNAME=your_email@example.com       # Your Jira login email
   JIRA_API_TOKEN=your_api_token_or_pat       # Your generated API Token or PAT
   

   • Security:
     • Never commit your .env file to version control! Add .env to your .gitignore file.
     • Jira Cloud: Generate an API token from your Atlassian account settings: Manage API tokens.
     • Jira Server/Data Center: Generate a Personal Access Token (PAT) from your Jira user profile settings: Using Personal Access Tokens.

▶️ Running the Server (Standalone)

You can run the server independently for testing or other purposes:

1. Directly with Python:

   python jira_reporter_server.py
   

2. Using the FastMCP CLI:

   fastmcp run jira_reporter_server.py
   

   To run with SSE (e.g., for remote access):

   fastmcp run jira_reporter_server.py --transport sse --port 8001
   

🖥️ Using with Claude Desktop

To make this server available as a tool within the Claude Desktop application:

1. Ensure Prerequisites: Make sure fastmcp is installed and accessible in your system's PATH, as the configuration below uses the fastmcp command.

2. Locate Claude Config File: Find the claude_desktop_config.json file. Its location depends on your operating system:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json (usually C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json)
   • Linux: ~/.config/Claude/claude_desktop_config.json (or $XDG_CONFIG_HOME/Claude/)

3. Edit the Config File: Open claude_desktop_config.json in a text editor.

4. Add Server Configuration: Find the "mcpServers" object within the JSON (if it doesn't exist, create it as an empty object {}). Add the following entry inside mcpServers, making sure to replace "path/to/your/jira_reporter_server.py" with the absolute path to your script:

   {
     "mcpServers": {
       // ... other servers might be here ...
   
       "jira_report": {
         "command": "fastmcp",
         "args": [
           "run",
           "/path/to/your/jira_reporter_server.py" // <-- IMPORTANT: Use the full, absolute path here
         ]
       }
   
       // ... other servers might be here ...
     }
     // ... rest of your Claude config ...
   }
   

   • "jira_report": This is the internal name Claude uses. You can change it if desired.
   • "command": "fastmcp": Tells Claude to use the fastmcp command-line tool.
   • "args": [...]: Tells Claude to run fastmcp run /path/to/your/jira_reporter_server.py.

5. Save and Restart: Save the claude_desktop_config.json file and restart the Claude Desktop application.

6. Invoke the Tool: You should now be able to use the tool in Claude by mentioning the server name defined in the Python script (Jira Weekly Reporter). For example: @Jira Weekly Reporter generate jira report for project MYPROJ and summarize it

🛠️ MCP Tool Details

• Tool Name: generate_jira_report
• Description: Generates a report of Jira issues based on a JQL query (defaulting to recently updated). Optionally summarizes the report using the client's LLM.

Parameters:

Parameter	Type	Required	Default	Description
jql_query	string	No	updated >= -7d ORDER BY updated DESC	Optional JQL query. If omitted, the default is used.
project_key	string	No	None	Optional Jira project key (e.g., "PROJ") to limit the search scope (added as project = 'KEY' AND ...).
max_results	integer	No	50	Maximum number of issues to include in the raw report data.
summarize	boolean	No	false	If true, the server will request a summary from the client's LLM via ctx.sample().

📦 Server Dependencies

The FastMCP constructor includes dependencies=["jira"]. This tells tools like fastmcp install that the jira library is required for this server to function correctly when creating isolated environments.

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

📄 License

MIT License