# MCP Server for Jira and Confluence
A Model Context Protocol (MCP) server that integrates with Atlassian's Jira and Confluence, enabling AI assistants to interact with these tools directly.
## Features
- **Jira Integration**
- List recent issues
- View issue details including comments
- Create new issues
- Add comments to issues
- Transition issues between statuses
- **Confluence Integration**
- List recent pages
- View page content
- Create new pages
- Update existing pages
- Add comments to pages
- Search pages using CQL (Confluence Query Language)
- Get specific pages by ID or title
- Ask questions about page content
- **AI-Powered Prompts**
- Summarize Jira issues
- Create structured Jira issue descriptions
- Summarize Confluence pages
- Generate structured Confluence content
## Installation
1. Clone the repository
2. Install dependencies using `uv`:
```bash
pip install uv
uv pip install -e .
```
## Configuration
### Environment Variables
Set the following environment variables to configure the server:
#### Jira Configuration
- `JIRA_URL`: Base URL of your Jira instance (e.g., `https://yourcompany.atlassian.net`)
- `JIRA_USERNAME`: Your Jira username/email
- `JIRA_API_TOKEN`: Your Jira API token or password
- `JIRA_PERSONAL_TOKEN`: Personal access token (alternative to username/API token)
#### Confluence Configuration
- `CONFLUENCE_URL`: Base URL of your Confluence instance (e.g., `https://yourcompany.atlassian.net/wiki`)
- `CONFLUENCE_USERNAME`: Your Confluence username/email
- `CONFLUENCE_API_TOKEN`: Your Confluence API token or password
- `CONFLUENCE_PERSONAL_TOKEN`: Personal access token (alternative to username/API token)
### Quick Setup
1. Create API tokens from your Atlassian account settings
2. Set environment variables in your shell:
```bash
export JIRA_URL="https://yourcompany.atlassian.net"
export JIRA_USERNAME="your-email@company.com"
export JIRA_API_TOKEN="your-jira-api-token"
export CONFLUENCE_URL="https://yourcompany.atlassian.net/wiki"
export CONFLUENCE_USERNAME="your-email@company.com"
export CONFLUENCE_API_TOKEN="your-confluence-api-token"
```
3. Or use the provided `run.sh` script with environment variables
## Usage
### Starting the Server
Run the server directly:
```bash
python -m mcp_jira_confluence.server
```
### VSCode MCP Extension
If using with the VSCode MCP extension, the server is automatically configured via `.vscode/mcp.json`.
### Claude Desktop
To use with Claude Desktop, add the following configuration:
On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
<details>
<summary>Development/Unpublished Servers Configuration</summary>
```json
"mcpServers": {
"mcp-jira-confluence": {
"command": "uv",
"args": [
"--directory",
"/Users/annmariyajoshy/vibecoding/mcp-jira-confluence",
"run",
"mcp-jira-confluence"
]
}
}
```
</details>
<details>
<summary>Published Servers Configuration</summary>
```json
"mcpServers": {
"mcp-jira-confluence": {
"command": "uvx",
"args": [
"mcp-jira-confluence"
]
}
}
```
</details>
## Resources
The server exposes the following types of resources:
- `jira://issue/{ISSUE_KEY}` - Jira issues
- `confluence://page/{PAGE_ID}` - Confluence pages
- `confluence://space/{SPACE_KEY}/page/{PAGE_ID}` - Confluence pages with space key
## Usage
### Available Tools
#### Jira Tools
- **`create-jira-issue`**: Create a new Jira issue
- **`comment-jira-issue`**: Add a comment to an issue
- **`transition-jira-issue`**: Change an issue's status
#### Confluence Tools
- **`create-confluence-page`**: Create a new Confluence page
- **`update-confluence-page`**: Update an existing page (version auto-fetched if not provided)
- **`comment-confluence-page`**: Add a comment to a page
- **`get-confluence-page`**: Get a specific page with optional comments/history
- **`search-confluence`**: Search pages using CQL queries
- **`ask-confluence-page`**: Ask questions about page content
### Usage Examples
#### Getting a Confluence Page
```
You can retrieve a page using either its ID or title + space key:
By ID:
- page_id: "123456789"
- include_comments: true
- include_history: false
By title and space:
- title: "API Documentation"
- space_key: "DEV"
- include_comments: false
```
#### Searching Confluence Pages
```
Search using CQL (Confluence Query Language):
Simple text search:
- query: "API Documentation"
- max_results: 10
Search by title:
- query: "title ~ 'API Documentation'"
- max_results: 10
Search in specific space:
- query: "space.key = 'DEV'"
- space_key: "DEV"
- max_results: 5
Recent pages:
- query: "lastmodified >= now('-7d')"
Note: The system automatically adds "type = page" to queries that don't specify a content type.
```
#### Asking Questions About Pages
```
Ask specific questions about page content:
- page_id: "123456789"
- question: "What are the main features described?"
- context_type: "summary" | "details" | "specific"
Or using title + space:
- title: "User Guide"
- space_key: "DOCS"
- question: "How do I configure authentication?"
- context_type: "details"
```
#### Common CQL Query Examples
- Simple text search: `"API Documentation"` (searches in content and title)
- Search by title: `title ~ "API Documentation"`
- Search in space: `space.key = "DEV"`
- Recent pages: `lastmodified >= now("-7d")`
- By author: `creator = "john.doe"`
- Combined: `title ~ "API" AND space.key = "DEV" AND lastmodified >= now("-30d")`
- Text in content: `text ~ "authentication method"`
Note: All queries automatically include `type = page` unless explicitly specified otherwise.
### Available Prompts
#### AI-Powered Analysis
- **`summarize-jira-issue`**: Create a summary of a Jira issue
- **`create-jira-description`**: Generate a structured issue description
- **`summarize-confluence-page`**: Create a summary of a Confluence page
- **`create-confluence-content`**: Generate structured Confluence content
- **`answer-confluence-question`**: Answer questions about specific page content
### Context Types for Question Answering
- **`summary`**: Quick answers using first 1000-1500 characters
- **`details`**: Comprehensive answers using full page content
- **`specific`**: Full content with enhanced filtering (future feature)
For detailed Confluence tool documentation and advanced CQL examples, see [CONFLUENCE_TOOLS.md](CONFLUENCE_TOOLS.md).
## Practical Examples
### Workflow: Research and Documentation
1. **Search for relevant pages**: Use `search-confluence` to find pages related to your topic
2. **Get page details**: Use `get-confluence-page` to retrieve full content with comments
3. **Ask specific questions**: Use `ask-confluence-page` to extract specific information
4. **Create summaries**: Use `summarize-confluence-page` prompt for quick overviews
### Common Use Cases
#### Finding Documentation
```
"Search for all API documentation in the DEV space that was updated in the last month"
→ Use search-confluence with query: "type = page AND space.key = 'DEV' AND title ~ 'API' AND lastmodified >= now('-30d')"
```
#### Getting Page Information
```
"Get the User Guide page from DOCS space with all comments"
→ Use get-confluence-page with title: "User Guide", space_key: "DOCS", include_comments: true
```
#### Content Analysis
```
"What authentication methods are supported according to the API documentation?"
→ Use ask-confluence-page with the API doc page ID and your specific question
```
#### Knowledge Extraction
```
"Summarize the key points from the deployment guide"
→ Use summarize-confluence-page prompt with the deployment guide page ID
```
## Development
### Building and Publishing
To prepare the package for distribution:
1. Sync dependencies and update lockfile:
```bash
uv sync
```
2. Build package distributions:
```bash
uv build
```
This will create source and wheel distributions in the `dist/` directory.
3. Publish to PyPI:
```bash
uv publish
```
Note: You'll need to set PyPI credentials via environment variables or command flags:
- Token: `--token` or `UV_PUBLISH_TOKEN`
- Or username/password: `--username`/`UV_PUBLISH_USERNAME` and `--password`/`UV_PUBLISH_PASSWORD`
### Debugging
Since MCP servers run over stdio, debugging can be challenging. For the best debugging
experience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:
```bash
npx @modelcontextprotocol/inspector uv --directory /Users/annmariyajoshy/vibecoding/mcp-jira-confluence run mcp-jira-confluence
```
Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
## Changelog
### Version 0.2.0 (2025-07-27)
**Major Improvements:**
- **Fixed EmbeddedResource validation errors** - All tools now use the correct MCP structure with `type: "resource"` and proper `TextResourceContents` format
- **Enhanced Confluence formatting** - Dramatically improved markdown to Confluence conversion:
- Proper list handling (grouped `<ul>`/`<ol>` tags instead of individual ones)
- Better code block formatting with language support
- Improved inline formatting (bold, italic, code, links)
- Smarter paragraph handling
- More robust markdown detection patterns
- **Fixed HTTP 409 conflicts** - Made version parameter optional in `update-confluence-page` with automatic version fetching
- **Added missing Confluence tools** - Implemented `get-confluence-page` and `search-confluence-pages` with proper CQL support
- **Improved error handling** - Better error messages and validation throughout
**Technical Changes:**
- Rewrote `ConfluenceFormatter.markdown_to_confluence()` with line-by-line processing
- Added regex-based markdown detection with multiple pattern matching
- Enhanced `_process_inline_formatting()` helper for consistent formatting
- Improved version conflict resolution in page updates
- Added comprehensive logging for format detection and conversion
### Version 0.1.9 (2025-07-26)
- Initial PyPI release with basic Jira and Confluence functionality
- Fixed basic EmbeddedResource structure issues
- Added core tool implementations
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-jira-confluence",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "atlassian, confluence, jira, mcp, model-context-protocol",
"author": null,
"author_email": "akhilthomas236 <akhilthomas236@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/51/64/7c53ad022877349aecbb44209bba8babe1d5638db722a64903a87b8d0835/mcp_jira_confluence-0.2.1.tar.gz",
"platform": null,
"description": "# MCP Server for Jira and Confluence\n\nA Model Context Protocol (MCP) server that integrates with Atlassian's Jira and Confluence, enabling AI assistants to interact with these tools directly.\n\n## Features\n\n- **Jira Integration**\n - List recent issues\n - View issue details including comments\n - Create new issues\n - Add comments to issues\n - Transition issues between statuses\n\n- **Confluence Integration**\n - List recent pages\n - View page content\n - Create new pages\n - Update existing pages\n - Add comments to pages\n - Search pages using CQL (Confluence Query Language)\n - Get specific pages by ID or title\n - Ask questions about page content\n\n- **AI-Powered Prompts**\n - Summarize Jira issues\n - Create structured Jira issue descriptions\n - Summarize Confluence pages\n - Generate structured Confluence content\n\n## Installation\n\n1. Clone the repository\n2. Install dependencies using `uv`:\n\n```bash\npip install uv\nuv pip install -e .\n```\n\n## Configuration\n\n### Environment Variables\n\nSet the following environment variables to configure the server:\n\n#### Jira Configuration\n- `JIRA_URL`: Base URL of your Jira instance (e.g., `https://yourcompany.atlassian.net`)\n- `JIRA_USERNAME`: Your Jira username/email\n- `JIRA_API_TOKEN`: Your Jira API token or password\n- `JIRA_PERSONAL_TOKEN`: Personal access token (alternative to username/API token)\n\n#### Confluence Configuration\n- `CONFLUENCE_URL`: Base URL of your Confluence instance (e.g., `https://yourcompany.atlassian.net/wiki`)\n- `CONFLUENCE_USERNAME`: Your Confluence username/email\n- `CONFLUENCE_API_TOKEN`: Your Confluence API token or password\n- `CONFLUENCE_PERSONAL_TOKEN`: Personal access token (alternative to username/API token)\n\n### Quick Setup\n\n1. Create API tokens from your Atlassian account settings\n2. Set environment variables in your shell:\n\n```bash\nexport JIRA_URL=\"https://yourcompany.atlassian.net\"\nexport JIRA_USERNAME=\"your-email@company.com\"\nexport JIRA_API_TOKEN=\"your-jira-api-token\"\n\nexport CONFLUENCE_URL=\"https://yourcompany.atlassian.net/wiki\"\nexport CONFLUENCE_USERNAME=\"your-email@company.com\"\nexport CONFLUENCE_API_TOKEN=\"your-confluence-api-token\"\n```\n\n3. Or use the provided `run.sh` script with environment variables\n\n## Usage\n\n### Starting the Server\n\nRun the server directly:\n\n```bash\npython -m mcp_jira_confluence.server\n```\n\n### VSCode MCP Extension\n\nIf using with the VSCode MCP extension, the server is automatically configured via `.vscode/mcp.json`.\n\n### Claude Desktop\n\nTo use with Claude Desktop, add the following configuration:\n\nOn MacOS: `~/Library/Application\\ Support/Claude/claude_desktop_config.json`\nOn Windows: `%APPDATA%/Claude/claude_desktop_config.json`\n\n<details>\n <summary>Development/Unpublished Servers Configuration</summary>\n \n```json\n\"mcpServers\": {\n \"mcp-jira-confluence\": {\n \"command\": \"uv\",\n \"args\": [\n \"--directory\",\n \"/Users/annmariyajoshy/vibecoding/mcp-jira-confluence\",\n \"run\",\n \"mcp-jira-confluence\"\n ]\n }\n }\n ```\n</details>\n\n<details>\n <summary>Published Servers Configuration</summary>\n \n```json\n\"mcpServers\": {\n \"mcp-jira-confluence\": {\n \"command\": \"uvx\",\n \"args\": [\n \"mcp-jira-confluence\"\n ]\n }\n}\n```\n</details>\n\n## Resources\n\nThe server exposes the following types of resources:\n\n- `jira://issue/{ISSUE_KEY}` - Jira issues\n- `confluence://page/{PAGE_ID}` - Confluence pages\n- `confluence://space/{SPACE_KEY}/page/{PAGE_ID}` - Confluence pages with space key\n\n## Usage\n\n### Available Tools\n\n#### Jira Tools\n- **`create-jira-issue`**: Create a new Jira issue\n- **`comment-jira-issue`**: Add a comment to an issue\n- **`transition-jira-issue`**: Change an issue's status\n\n#### Confluence Tools\n- **`create-confluence-page`**: Create a new Confluence page\n- **`update-confluence-page`**: Update an existing page (version auto-fetched if not provided)\n- **`comment-confluence-page`**: Add a comment to a page\n- **`get-confluence-page`**: Get a specific page with optional comments/history\n- **`search-confluence`**: Search pages using CQL queries\n- **`ask-confluence-page`**: Ask questions about page content\n\n### Usage Examples\n\n#### Getting a Confluence Page\n```\nYou can retrieve a page using either its ID or title + space key:\n\nBy ID:\n- page_id: \"123456789\"\n- include_comments: true\n- include_history: false\n\nBy title and space:\n- title: \"API Documentation\"\n- space_key: \"DEV\"\n- include_comments: false\n```\n\n#### Searching Confluence Pages\n```\nSearch using CQL (Confluence Query Language):\n\nSimple text search:\n- query: \"API Documentation\"\n- max_results: 10\n\nSearch by title:\n- query: \"title ~ 'API Documentation'\"\n- max_results: 10\n\nSearch in specific space:\n- query: \"space.key = 'DEV'\"\n- space_key: \"DEV\"\n- max_results: 5\n\nRecent pages:\n- query: \"lastmodified >= now('-7d')\"\n\nNote: The system automatically adds \"type = page\" to queries that don't specify a content type.\n```\n\n#### Asking Questions About Pages\n```\nAsk specific questions about page content:\n\n- page_id: \"123456789\"\n- question: \"What are the main features described?\"\n- context_type: \"summary\" | \"details\" | \"specific\"\n\nOr using title + space:\n- title: \"User Guide\"\n- space_key: \"DOCS\"\n- question: \"How do I configure authentication?\"\n- context_type: \"details\"\n```\n\n#### Common CQL Query Examples\n- Simple text search: `\"API Documentation\"` (searches in content and title)\n- Search by title: `title ~ \"API Documentation\"`\n- Search in space: `space.key = \"DEV\"`\n- Recent pages: `lastmodified >= now(\"-7d\")`\n- By author: `creator = \"john.doe\"`\n- Combined: `title ~ \"API\" AND space.key = \"DEV\" AND lastmodified >= now(\"-30d\")`\n- Text in content: `text ~ \"authentication method\"`\n\nNote: All queries automatically include `type = page` unless explicitly specified otherwise.\n\n### Available Prompts\n\n#### AI-Powered Analysis\n- **`summarize-jira-issue`**: Create a summary of a Jira issue\n- **`create-jira-description`**: Generate a structured issue description\n- **`summarize-confluence-page`**: Create a summary of a Confluence page\n- **`create-confluence-content`**: Generate structured Confluence content\n- **`answer-confluence-question`**: Answer questions about specific page content\n\n### Context Types for Question Answering\n- **`summary`**: Quick answers using first 1000-1500 characters\n- **`details`**: Comprehensive answers using full page content\n- **`specific`**: Full content with enhanced filtering (future feature)\n\nFor detailed Confluence tool documentation and advanced CQL examples, see [CONFLUENCE_TOOLS.md](CONFLUENCE_TOOLS.md).\n\n## Practical Examples\n\n### Workflow: Research and Documentation\n1. **Search for relevant pages**: Use `search-confluence` to find pages related to your topic\n2. **Get page details**: Use `get-confluence-page` to retrieve full content with comments\n3. **Ask specific questions**: Use `ask-confluence-page` to extract specific information\n4. **Create summaries**: Use `summarize-confluence-page` prompt for quick overviews\n\n### Common Use Cases\n\n#### Finding Documentation\n```\n\"Search for all API documentation in the DEV space that was updated in the last month\"\n\u2192 Use search-confluence with query: \"type = page AND space.key = 'DEV' AND title ~ 'API' AND lastmodified >= now('-30d')\"\n```\n\n#### Getting Page Information\n```\n\"Get the User Guide page from DOCS space with all comments\"\n\u2192 Use get-confluence-page with title: \"User Guide\", space_key: \"DOCS\", include_comments: true\n```\n\n#### Content Analysis\n```\n\"What authentication methods are supported according to the API documentation?\"\n\u2192 Use ask-confluence-page with the API doc page ID and your specific question\n```\n\n#### Knowledge Extraction\n```\n\"Summarize the key points from the deployment guide\"\n\u2192 Use summarize-confluence-page prompt with the deployment guide page ID\n```\n\n## Development\n\n### Building and Publishing\n\nTo prepare the package for distribution:\n\n1. Sync dependencies and update lockfile:\n```bash\nuv sync\n```\n\n2. Build package distributions:\n```bash\nuv build\n```\n\nThis will create source and wheel distributions in the `dist/` directory.\n\n3. Publish to PyPI:\n```bash\nuv publish\n```\n\nNote: You'll need to set PyPI credentials via environment variables or command flags:\n- Token: `--token` or `UV_PUBLISH_TOKEN`\n- Or username/password: `--username`/`UV_PUBLISH_USERNAME` and `--password`/`UV_PUBLISH_PASSWORD`\n\n### Debugging\n\nSince MCP servers run over stdio, debugging can be challenging. For the best debugging\nexperience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).\n\n\nYou can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:\n\n```bash\nnpx @modelcontextprotocol/inspector uv --directory /Users/annmariyajoshy/vibecoding/mcp-jira-confluence run mcp-jira-confluence\n```\n\n\nUpon launching, the Inspector will display a URL that you can access in your browser to begin debugging.\n\n## Changelog\n\n### Version 0.2.0 (2025-07-27)\n\n**Major Improvements:**\n\n- **Fixed EmbeddedResource validation errors** - All tools now use the correct MCP structure with `type: \"resource\"` and proper `TextResourceContents` format\n- **Enhanced Confluence formatting** - Dramatically improved markdown to Confluence conversion:\n - Proper list handling (grouped `<ul>`/`<ol>` tags instead of individual ones)\n - Better code block formatting with language support\n - Improved inline formatting (bold, italic, code, links)\n - Smarter paragraph handling\n - More robust markdown detection patterns\n- **Fixed HTTP 409 conflicts** - Made version parameter optional in `update-confluence-page` with automatic version fetching\n- **Added missing Confluence tools** - Implemented `get-confluence-page` and `search-confluence-pages` with proper CQL support\n- **Improved error handling** - Better error messages and validation throughout\n\n**Technical Changes:**\n\n- Rewrote `ConfluenceFormatter.markdown_to_confluence()` with line-by-line processing\n- Added regex-based markdown detection with multiple pattern matching\n- Enhanced `_process_inline_formatting()` helper for consistent formatting\n- Improved version conflict resolution in page updates\n- Added comprehensive logging for format detection and conversion\n\n### Version 0.1.9 (2025-07-26)\n\n- Initial PyPI release with basic Jira and Confluence functionality\n- Fixed basic EmbeddedResource structure issues\n- Added core tool implementations",
"bugtrack_url": null,
"license": "MIT",
"summary": "Model Context Protocol server for Jira and Confluence",
"version": "0.2.1",
"project_urls": {
"Documentation": "https://github.com/akhilthomas236/mcp-jira-confluence/blob/main/README.md",
"Homepage": "https://github.com/akhilthomas236/mcp-jira-confluence",
"Issues": "https://github.com/akhilthomas236/mcp-jira-confluence/issues",
"Repository": "https://github.com/akhilthomas236/mcp-jira-confluence"
},
"split_keywords": [
"atlassian",
" confluence",
" jira",
" mcp",
" model-context-protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a37705d9f286519d32178c57526c2f931efc34250d86efecf87415760c60cd84",
"md5": "db8291b50dc93f220360cc547d181db2",
"sha256": "4af9b4a5ea0fceb3b2677a8d071cac948c0710588022dc1ffa9f80db2412e5dd"
},
"downloads": -1,
"filename": "mcp_jira_confluence-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "db8291b50dc93f220360cc547d181db2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 23081,
"upload_time": "2025-07-27T03:03:41",
"upload_time_iso_8601": "2025-07-27T03:03:41.423710Z",
"url": "https://files.pythonhosted.org/packages/a3/77/05d9f286519d32178c57526c2f931efc34250d86efecf87415760c60cd84/mcp_jira_confluence-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "51647c53ad022877349aecbb44209bba8babe1d5638db722a64903a87b8d0835",
"md5": "66365ed0073d73385f2f5e11ba84670e",
"sha256": "f83d42a71a7388bd37c8573972e6b397eecf47612afc2a7d52c672ccc11c160a"
},
"downloads": -1,
"filename": "mcp_jira_confluence-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "66365ed0073d73385f2f5e11ba84670e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 33430,
"upload_time": "2025-07-27T03:03:43",
"upload_time_iso_8601": "2025-07-27T03:03:43.170591Z",
"url": "https://files.pythonhosted.org/packages/51/64/7c53ad022877349aecbb44209bba8babe1d5638db722a64903a87b8d0835/mcp_jira_confluence-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 03:03:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "akhilthomas236",
"github_project": "mcp-jira-confluence",
"github_not_found": true,
"lcname": "mcp-jira-confluence"
}
JSON
