Connect Jira to MXCP with OAuth

This example shows how to connect JIRA to MXCP using secure OAuth authentication.

What You Get

Once configured, you can query your Jira data directly from MXCP:

-- Find all issues assigned to you
SELECT jql_query_jira('assignee = currentUser()') AS my_issues;

-- Get recent bugs in a project
SELECT jql_query_jira('project = MYPROJECT AND type = Bug AND created >= -7d') AS recent_bugs;

-- List all your accessible projects
SELECT list_projects_jira() AS projects;

-- Get user information
SELECT get_user_jira('john.doe@company.com') AS user_info;

Quick Setup Guide

Step 1: Create Your OAuth App in Atlassian

Go to Atlassian Developer Console
Click Create → OAuth 2.0 (3LO)
Fill in your app details:
- App name: MXCP Jira Integration (or whatever you prefer)
- Description: OAuth integration for MXCP
Click Create

Step 2: Configure OAuth Settings

After creating your app:

Click on your newly created app
Go to Permissions → Add → Jira API
Add these scopes:
- read:me (to read your own profile information)
- read:jira-work (to read issues and projects)
- read:jira-user (to read user information)
- offline_access (to refresh tokens)
Go to Authorization → OAuth 2.0 (3LO)
Add your callback URL based on your deployment:
- For production: https://your-domain.com/atlassian/callback
- For local development: http://localhost:8000/atlassian/callback
- For ngrok testing: https://your-ngrok-url.ngrok.io/atlassian/callback
Important: Save your Client ID and Client Secret - you'll need these next!

Step 3: Set Up Environment Variables

Create a .env file or set these environment variables:

export ATLASSIAN_CLIENT_ID="your-client-id-here"
export ATLASSIAN_CLIENT_SECRET="your-client-secret-here"

Step 4: Configure MXCP

This example includes a ready-to-use config.yml file that you can customize with your OAuth credentials. You can either:

Use the included file: Edit the existing config.yml in this directory
Create your own: Use the template below

Configuration template:

mxcp: 1.0.0
transport:
  http:
    port: 8000
    host: 0.0.0.0
    # Set base_url to your server's public URL for production
    base_url: http://localhost:8000

projects:
  my-jira-project:
    profiles:
      dev:
        # OAuth Configuration
        auth:
          provider: atlassian
          clients:
            - client_id: "${ATLASSIAN_CLIENT_ID}"
              client_secret: "${ATLASSIAN_CLIENT_SECRET}"
              name: "MXCP Jira Integration"
              redirect_uris:
                # For production, use your actual domain (must match base_url above)
                - "https://your-domain.com/atlassian/callback"
                # For local development, uncomment the line below:
                # - "http://localhost:8000/atlassian/callback"
              scopes:
                - "mxcp:access"
          atlassian:
            client_id: "${ATLASSIAN_CLIENT_ID}"
            client_secret: "${ATLASSIAN_CLIENT_SECRET}"
            scope: "read:me read:jira-work read:jira-user offline_access"
            callback_path: "/atlassian/callback"
            auth_url: "https://auth.atlassian.com/authorize"
            token_url: "https://auth.atlassian.com/oauth/token"
        
        # Plugin Configuration (minimal setup required!)
        plugin:
          config:
            jira_oauth: {}  # Named 'jira_oauth' here, but UDFs use 'jira' suffix from mxcp-site.yml

Step 5: Install and Run

Install dependencies:

pip install atlassian-python-api requests

Start MXCP:

# From the examples/jira-oauth directory:
MXCP_CONFIG=config.yml mxcp serve

Authenticate:
- Configure the MXCP server in your MCP client (e.g., Claude Desktop)
- When the client connects, you'll be redirected to Atlassian to authorize the app
- After authorization, you'll be redirected back to your MCP client
- You're now ready to query Jira!

Available Functions

Function	Description	Example
`jql_query_jira(query, start, limit)`	Execute JQL queries	`SELECT jql_query_jira('project = TEST')`
`list_projects_jira()`	List all your accessible projects	`SELECT list_projects_jira()`
`get_project_jira(key)`	Get details for a specific project	`SELECT get_project_jira('TEST')`
`get_user_jira(username)`	Get user information	`SELECT get_user_jira('john@company.com')`

Example Queries

-- Get your assigned issues
SELECT jql_query_jira('assignee = currentUser() AND status != Done', 0, 20) AS my_open_issues;

-- Find high priority bugs
SELECT jql_query_jira('priority = High AND type = Bug', 0, 10) AS high_priority_bugs;

-- Recent activity in a project
SELECT jql_query_jira('project = MYPROJECT AND updated >= -3d') AS recent_activity;

-- Get project information
SELECT 
    list_projects_jira() AS all_projects,
    get_project_jira('MYPROJECT') AS project_details;

-- Find issues by reporter
SELECT jql_query_jira('reporter = "john.doe@company.com"') AS johns_issues;

5.2 KiB Raw Permalink Blame History