jira-kb-mcp

A local knowledge base built from your Jira project's history, exposed as an MCP server so any MCP-capable AI assistant (Claude Desktop, Claude Code, Kiro, ChatGPT in Developer Mode) can search past issues and their resolutions while helping you troubleshoot a new one.

Everything runs locally. No database server, no cloud account, no API key required by default:

• Storage: LanceDB, an embedded vector database. One local directory, no server process.

• Embeddings: fastembed running a multilingual model on ONNX Runtime, fully offline, no GPU needed.

• Search: hybrid (semantic + BM25 keyword) search over your indexed issues, so both "something like this happened before" and "the exact error code" queries work.

• Topics: issues are clustered so you get a browsable index of recurring themes, not just a flat list of tickets.

How it works

1. jira-kb init — one-time setup, stores your Jira URL/email/API token in ~/.jira-kb-mcp/.env (never committed, file permissions locked to your user).

2. jira-kb sync PROJECT_KEY — pulls every issue (summary, description, comments, resolution) from a Jira project via the REST API, embeds it, and stores it locally. Safe to re-run: subsequent syncs are incremental.

3. Point your AI assistant at the MCP server (see below) and ask it things like "have we seen a timeout like this before in PROJ?" — it will call search_cases and ground its answer in your real ticket history.

You can also use it as a plain CLI without any AI assistant involved: jira-kb search "some description of the problem".

Related MCP server: Qurio MCP Server

Requirements

• Python 3.10+

• A Jira Cloud site and an API token for your account (Jira Server/Data Center is not supported yet — see Limitations below)

Install

git clone <this-repo-url> jira-kb-mcp
cd jira-kb-mcp
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

Setup

jira-kb init

This prompts for your Jira URL, account email, and API token, and saves them to ~/.jira-kb-mcp/.env. You can also copy env.example to .env yourself and fill it in manually — either in the current directory or in ~/.jira-kb-mcp/.env.

Index a project

jira-kb sync PROJ            # incremental sync (default)
jira-kb sync PROJ --full     # force full re-index

This fetches every issue in the project (paginated, using Jira's current /rest/api/3/search/jql endpoint), embeds the summary + description + comments, and stores it in ~/.jira-kb-mcp/lancedb/. Re-running sync only fetches issues updated since the last run.

Use it from the CLI

jira-kb search "connection timeout when calling payment gateway"
jira-kb topics
jira-kb stats PROJ

Use it as an MCP agent

The server exposes these tools: sync_jira_project, search_cases_tool, get_case, list_topics_tool, get_project_stats.

Claude Desktop / Claude Code / Kiro (stdio)

Add to your MCP config (claude_desktop_config.json, .mcp.json, or Kiro's .kiro/settings/mcp.json):

{
  "mcpServers": {
    "jira-kb": {
      "command": "/absolute/path/to/jira-kb-mcp/.venv/bin/jira-kb",
      "args": ["mcp"]
    }
  }
}

Restart the assistant, and it will be able to call the tools above during a conversation.

ChatGPT (Developer Mode, streamable-http)

ChatGPT's MCP support requires an HTTP(S) endpoint, it cannot launch a local stdio process the way Claude/Kiro do. Run the server over HTTP:

jira-kb mcp --transport streamable-http --port 8000

This serves http://127.0.0.1:8000/mcp. To connect it from ChatGPT you need that URL to be reachable from OpenAI's servers, which means either:

• Deploying the server somewhere with a public HTTPS URL, or

• Using a tunnel (e.g. ngrok http 8000) for local testing.

Security note: exposing this server to the internet exposes your Jira issue data (via the tools) to anyone who can reach that URL. This project does not implement authentication on the HTTP transport. If you expose it beyond your own machine, put it behind your own auth (reverse proxy, VPN, or a tunnel provider's access controls) — do not expose it publicly unauthenticated.

Configuration reference

All settings are environment variables (see env.example):

Limitations

• Jira Cloud only (uses the current /rest/api/3/search/jql REST endpoint). Jira Server/Data Center support is not implemented.

• Topic detection is unsupervised clustering with TF-IDF labels, not an LLM summary — labels are keyword lists, not full sentences. It also needs a minimum number of indexed issues (5) to produce any clusters.

• Read-only: this tool never writes back to Jira.

• The streamable-http transport has no built-in authentication (see security note above).

• Search quality depends on top_k. The default multilingual embedding model (384 dimensions) ranks well when your query shares vocabulary with the ticket (e.g. an error code, a feature name), but a long paraphrase with no shared keywords (e.g. "disable the second factor for a user" when every ticket says "2FA") may rank lower than expected in a very small top_k. If a search feels like it's missing an obvious match, retry with a larger --top-k before concluding it isn't indexed.

License

MIT — see LICENSE.