Frequently Asked Questions

Shoal is a free, open-source MCP server for Jira. It lets AI assistants like Claude read, create, update, search, and transition Jira issues - without the bugs, hangs, and missing fields found in the official integration. Install it once and use it from any MCP-compatible client.

MCP (Model Context Protocol) is an open standard that lets AI assistants connect to external tools and data sources. An MCP server is a process that exposes a set of capabilities - in Shoal's case, issue tracking operations - that the AI can call during a conversation. The AI can read an issue, create a follow-up, search by JQL, or transition a status without you leaving the chat.

Shoal works with any MCP-compatible client. It has been tested with Claude Desktop and Claude Code. Any client that supports the MCP stdio transport should work.

Node.js 18 or later is required. Install Shoal globally with npm install -g @aquarium-tools/shoal. You will also need a Jira API token, which is free to generate from your Atlassian account settings.

No. Shoal is free and open-source (MIT license). There is no paid tier, no usage limit, and no account required on the Aquarium Apps side.

Set three environment variables before starting the MCP server: JIRA_BASE_URL (your Jira instance URL, e.g. https://yourorg.atlassian.net), JIRA_EMAIL (the email address on your Jira account), and JIRA_API_TOKEN (an API token generated from your Atlassian account). Add these to your MCP client's server configuration or to your shell environment before launching Shoal.

Log in to id.atlassian.com, go to Security → API tokens → Create API token. Give it a label like "Shoal" and copy the token - Atlassian only shows it once. Use this token as the value for JIRA_API_TOKEN.

Shoal supports:

• Get issue details (summary, description, status, assignee, priority, fields)
• Create issues with any standard or custom fields
• Update issue fields
• Add and edit comments
• Search using full JQL
• Transition issues through workflow steps
• Manage labels
• Create, list, and remove issue links
• Attach files
• List available transitions and link types
• List projects

Yes. Set JIRA_BASE_URL to your self-hosted instance URL. Authentication uses HTTP Basic auth with your Jira username and a password or personal access token, depending on your Jira version. Data Center instances on version 8.14 and later support personal access tokens.

Yes. The searchJiraIssuesUsingJql tool accepts any valid JQL expression. You can pass complex queries - filter by project, assignee, sprint, fix version, label, custom fields, or any combination. Results include configurable fields and pagination support.

No. Shoal runs entirely on your local machine. It does not have a backend, does not phone home, and does not log or cache any issue data. Every request goes directly from your machine to your Jira instance.

Credentials are stored wherever you put them - typically in environment variables set in your shell profile or your MCP client's configuration file. Shoal reads them at startup and never writes them anywhere. Aquarium Apps has no access to them.

Nothing. Shoal is a local process. There are no analytics, no telemetry, and no remote endpoints operated by Aquarium Apps. Your issue data never leaves your machine except in direct API calls to Jira.

Check that JIRA_BASE_URL is set correctly and includes the scheme (e.g. https://yourorg.atlassian.net - no trailing slash). Verify the URL by opening it in a browser. If you are on a self-hosted instance, confirm that your machine can reach it over the network.

The most common cause is a wrong or expired API token. Generate a fresh token from id.atlassian.com → Security → API tokens and update JIRA_API_TOKEN. Also confirm that JIRA_EMAIL matches the email on the Atlassian account that owns the token - the two must match exactly.

Confirm that the shoal binary is on your PATH - run which shoal in a terminal. If it's not found, the global npm install may have placed it in a directory not on your PATH. Check npm bin -g and add that directory to your PATH. Restart your MCP client after updating the configuration.

This is usually a network timeout reaching Jira. Check for proxy settings your machine requires - if you are behind a corporate proxy, set HTTPS_PROXY or HTTP_PROXY in the environment where Shoal runs. Also check whether your Jira instance is reachable from the terminal.