mcp-issues

mcp-issues

Ask Claude "what's blocked in this sprint?" and get real Jira data back.

Works with Claude Desktop · Cursor · Cline · Claude Code · VS Code Copilot — anything that speaks MCP.

A Go MCP server that exposes practical tools over your Jira instance plus semantic search (RAG) over an indexed corpus of issues.

Русский README →

Tools

Per-tool contracts: docs/tools/.

Transports:

• stdio — for Claude Desktop, Cursor, Claude Code.
• Streamable HTTP on /mcp with a static API key — for Claude Web, remote clients, multi-tenant setups.

Quickstart

Prerequisites: Go 1.26+, a Jira API token, a Voyage/OpenAI key (or a local ONNX model). A C toolchain (Xcode CLT on macOS, build-essential on Linux) is required for CGO (sqlite-vec).

# 1. Install (or build from source)
go install github.com/grevus/mcp-issues/cmd/mcp-issues@latest
go install github.com/grevus/mcp-issues/cmd/mcp-issues-index@latest

# 2. Configure — copy and fill in Jira + embedder credentials
cp .env.example .env

# 3. Migrate + index a project
mcp-issues-index migrate
mcp-issues-index index --project=ABC

# 4. Run (stdio for desktop clients)
mcp-issues --transport=stdio

No Docker needed — SQLite is the default store (~/.mcp-issues/knowledge.db).

Minimum .env:

JIRA_BASE_URL=https://your-org.atlassian.net
JIRA_EMAIL=you@example.com
JIRA_API_TOKEN=your-jira-api-token

RAG_EMBEDDER=voyage
VOYAGE_API_KEY=your-voyage-api-key

Get a Jira token at id.atlassian.com/manage-profile/security/api-tokens. Voyage AI key at dash.voyageai.com (free tier: 200M tokens).

SQLite is the default store — the DB lands at ~/.mcp-issues/knowledge.db (override with SQLITE_PATH). No Docker needed.

Connect to Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-issues": {
      "command": "/absolute/path/to/mcp-issues",
      "args": ["--transport=stdio"],
      "env": {
        "JIRA_BASE_URL": "https://your-org.atlassian.net",
        "JIRA_EMAIL": "you@example.com",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "RAG_EMBEDDER": "voyage",
        "VOYAGE_API_KEY": "your-voyage-key"
      }
    }
  }
}

Restart Claude Desktop — the 10 tools appear under the mcp-issues server.

For HTTP transport (Claude Web, remote clients):

MCP_API_KEY=your-secret-key mcp-issues --transport=http

Advanced: pgvector backend (Docker)

For production or large corpora (>100k issues), use Postgres + pgvector instead of SQLite.

docker compose up -d

export KNOWLEDGE_STORE=pgvector
export DATABASE_URL=postgres://mcp:mcp@localhost:15432/mcp

mcp-issues-index migrate
mcp-issues-index index --project=ABC
mcp-issues --transport=stdio

Configuration

All configuration is via environment variables (or a .env file in the working directory).

Jira

Knowledge store

Embedder

Embedding dimension is fixed at 1024. Choose one provider:

Transport

Indexing

The indexer fetches all issues in a project via JQL pagination, embeds each one, and stores them in the knowledge store.

mcp-issues-index index --project=ABC

Multi-tenant mode (keys file):

mcp-issues-index index --project=ABC --tenant=acme --keys-file=./keys.yaml

Re-indexing is idempotent — ReplaceProject atomically deletes and re-inserts all documents for that project key.

No built-in scheduler. Run via cron or CI, e.g.:

0 */6 * * * /path/to/mcp-issues-index index --project=ABC >> /var/log/mcp-issues-index.log 2>&1

Architecture

cmd/mcp-issues          stdio | streamable-http (Echo)
cmd/mcp-issues-index    migrate | index --project=ABC
  └─ internal/register          only importer of go-sdk/mcp
       └─ internal/handlers     pure business logic, knows nothing about mcp/echo
            └─ narrow interfaces (IssueLister, SprintReader, ...)
                 ├─ internal/tracker/jira     Jira REST/Agile client
                 └─ internal/knowledge        Store interface + Retriever
                      ├─ internal/knowledge/embed     Voyage / OpenAI / ONNX
                      ├─ internal/knowledge/pgvector  Postgres + pgvector
                      ├─ internal/knowledge/sqlite    SQLite + sqlite-vec
                      └─ internal/knowledge/index     Indexer (CLI)
  └─ internal/auth              stdlib middleware, constant-time key compare
  └─ internal/config            mode-aware env validation

Handlers take narrow interfaces, not a fat client — each tool is trivially unit-testable with a fake.

More context in CLAUDE.md.

Adding a new tool

The architecture is deliberately flat — no plugin registry, no DI container. Adding a tool is 4 files:

1. Method + DTO in internal/tracker/jira/
2. Handler in internal/handlers/<thing>.go (~30 lines, see issues.go as a reference)
3. Register one line in internal/register/register.go
4. Docs: copy docs/tools/_template.md → docs/tools/<name>.md

Full details in CONTRIBUTING.md. Good first issues: look for the good first issue label on GitHub Issues.

Contributing

See CONTRIBUTING.md for tests, code style, and PR workflow.

go test ./...                          # unit tests
go test -tags=integration ./...        # + pgvector via testcontainers (needs Docker)

License

MIT — see LICENSE.