Jira Weekly Reporter MCP Server

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

📦 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