Jira + GitHub MCP server

This is a portfolio demo, not a production integration. It shows how an AI agent can call Jira and GitHub through the Model Context Protocol. The default backend is an in-memory fake. Nothing here is affiliated with Atlassian or GitHub, and the live clients are thin REST wrappers rather than a hardened gateway.

What it demonstrates

• An MCP server built with the official Python SDK (mcp 2.x, MCPServer).

• Eight tools: search, create, comment, and transition on Jira; list pull requests, summarize a diff, create an issue, and comment on GitHub.

• Tokens come from the environment. The mock backend starts with no credentials.

• Input validation, a per-tool rate limit, read-only mode, and allowlists for tools, Jira projects, and GitHub repositories.

• JSON logs on stderr, so they do not collide with the MCP stdio stream. Argument values are not logged.

Related MCP server: jira-helper

Architecture

flowchart LR
    subgraph hosts [Agent hosts]
        Claude[Claude Desktop]
        Cursor[Cursor]
        Example[examples/agent_example.py]
    end

    subgraph server [jira_github_mcp]
        Guard[Guardrails]
        Tools[Jira and GitHub tools]
        Logs[JSON logs on stderr]
    end

    subgraph data [Backends]
        Mock[In-memory mock]
        Jira[Jira Cloud REST]
        GitHub[GitHub REST]
    end

    Claude --> Guard
    Cursor --> Guard
    Example --> Guard
    Guard --> Tools
    Tools --> Logs
    Tools -->|MCP_BACKEND=mock| Mock
    Tools -->|MCP_BACKEND=live| Jira
    Tools -->|MCP_BACKEND=live| GitHub

A client speaks MCP over stdin and stdout. Each tool call is checked against the allowlists and read-only flag, validated, then rate-limited. The service calls either the mock store or the live REST client. Logs go to stderr.

Tools

In live mode, a query that contains =, ~, ORDER BY, or IN ( is sent to Jira as JQL. Anything else is translated from the mock filter syntax. Results are still dropped when they fall outside JIRA_PROJECT_ALLOWLIST.

Mock workspace

The fake data is one small story so a demo agent has something to read:

• PLAT-101 (Bug, Open) — SSO callback drops state and returns 500.

• PLAT-102 (Story, In Progress) — audit every agent tool call.

• MOB-14 (Task, Open) — cache pull request summaries for a mobile review bot.

• acme/platform#41 — closed spike for an in-memory rate limiter.

• acme/platform#42 — open PR, structured audit logging (160 additions).

• acme/platform#43 — open PR, reject SSO callbacks that are missing state.

• acme/platform#7 — open issue documenting the mock query syntax.

The mock GitHub client only knows acme/platform. Other repositories return not found.

Setup

Requires Python 3.11+.

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Run the server on stdio (this is what Claude Desktop and Cursor launch; it waits for MCP messages):

python -m jira_github_mcp

Or the console script: jira-github-mcp.

Try the example client, which starts the server itself, lists the tools, searches Jira for the SSO bug, and summarizes pull request 43:

python examples/agent_example.py

That script forces MCP_BACKEND=mock and MCP_READ_ONLY=true.

Claude Desktop

Merge examples/claude_desktop_config.json into the Claude Desktop config (claude_desktop_config.json). jira-github-mcp must be on the PATH of the app, or replace command with the full path to the executable inside your virtualenv.

Cursor

Project config lives in .cursor/mcp.json. examples/cursor_mcp.json is a starting point: mock backend, read-only, limited to the PLAT project and acme/platform. Use the same Python environment that has this package installed.

Configuration

See .env.example. All of these are optional in mock mode.

Live mode refuses to start until the four credential variables are set. A Jira base URL that is not HTTPS is rejected so the token is not sent in the clear.

Security notes

• Tokens are read from the environment. They are not written to logs, and the repo has no sample secrets.

• Logs include the tool name, success flag, error code, and duration. They do not include argument values.

• Read-only mode and the allowlists are for safe demos. Turn read-only on before pointing a live token at an agent.

• The rate limit is in-memory and per process. Restarting the server clears it. It is not a quota system.

• Validation limits string length and checks the shape of issue keys, project keys, and repository names. It is not a JQL sandbox. In live mode, raw JQL is passed to Jira, and the token's own permissions are the real boundary. The project allowlist filters rows after the call.

• Live HTTP errors return a short status line to the agent. They do not include request headers.

• This demo does not do SSO, audit storage, secret scanning, or multi-tenant isolation.

Tests and CI

Unit tests talk to the mock store and to live clients with a fake HTTP transport. They do not call Jira or GitHub.

GitHub Actions (.github/workflows/ci.yml) installs the package, runs Ruff, and runs pytest on Python 3.12. That workflow is the test run for this repo.

ruff check .
pytest -q

Layout

src/jira_github_mcp/    MCP server, guardrails, mock and live clients
examples/               Claude Desktop config, Cursor config, example client
tests/                  pytest against the mock backends and fake HTTP
.github/workflows/ci.yml

Limitations

• Mock mode does not evaluate JQL. Use the field:value filters above.

• Live mode does not page past the first response, and a diff summary is aggregated from the pull request files API rather than a review of the patch.

• Jira auth is the Cloud email-plus-API-token pair, not a bearer personal access token.

• The mock workflow statuses are fixed. Live mode matches a transition by name or destination status, so the caller has to use a name that project actually has.

• There is no persistence. Mock writes disappear when the process exits.