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

Clone the Repository (if applicable):

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

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

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:

Directly with Python:
```
python jira_reporter_server.py
```

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:

Ensure Prerequisites: Make sure fastmcp is installed and accessible in your system's PATH, as the configuration below uses the fastmcp command.
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/)
Edit the Config File: Open claude_desktop_config.json in a text editor.
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.
Save and Restart: Save the claude_desktop_config.json file and restart the Claude Desktop application.
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

Jira Weekly Reporter MCP Server

✨ 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.

⚙️ Setup

Clone the Repository (if applicable):

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

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

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.

🖥️ Using with Claude Desktop

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

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

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/)

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

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.

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

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

updated >= -7d ORDER BY updated DESC

Optional JQL query. If omitted, the default is used.

project_key

string

None

Optional Jira project key (e.g., "PROJ") to limit the search scope (added as project = 'KEY' AND ...).

max_results

integer

50

Maximum number of issues to include in the raw report data.

summarize

boolean

false

If true, the server will request a summary from the client's LLM via ctx.sample().