README - jellyfish-mcp: A Jellyfish MCP Server by jellyfish-ai

jellyfish-mcp: A Jellyfish MCP Server

Security Notice: There are known risks and inherent limitations in this implementation. Refer to SECURITY.md before using.

Overview

A Model Context Protocol server for retrieving and analyzing data from Jellyfish's API. This server allows a host (e.g. Claude Desktop or Cursor) to interact with your Jellyfish instance, enabling natural language queries about your engineering metrics, team data, and other information available through the Jellyfish API.

Tools

The server provides several tools for interacting with the Jellyfish API:

General

get_api_schema - Retrieves the complete API schema with all available endpoints
list_endpoints - Lists all available API endpoints with their descriptions
get_endpoint - Makes GET requests to any available API endpoint

Allocations

allocations_by_person
allocations_by_team
allocations_by_investment_category
allocations_by_investment_category_person
allocations_by_investment_category_team
allocations_by_work_category
allocations_by_work_category_person
allocations_by_work_category_team
allocations_filter_fields
allocations_summary_by_investment_category
allocations_summary_by_work_category

Delivery

deliverable_details
deliverable_scope_and_effort_history
work_categories
work_category_contents

Metrics

company_metrics
person_metrics
team_metrics
team_sprint_summary
unlinked_pull_requests

People

list_engineers
search_people

Teams

list_teams
search_teams

Each tool corresponds to a specific Jellyfish API endpoint and allows you to retrieve or search for data as described in the API.

Setup

Jellyfish Setup

Generate an API token from your Jellyfish instance
- Go to the Data Connections page
- Click the API Export tab
- Click Generate New Token
- In the Generate New Token dialog, select a Time To Live value and click Generate. A new token is created and displayed in the dialog
- Copy the token (you will add it to your host application's config below)
- Close the dialog

Local Setup

Clone this repository:

git clone [repository-url]
cd jellyfish-mcp

Install uv if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

Restart your terminal or open a new terminal window to ensure uv is in your PATH.
Create a virtual environment and install dependencies:

uv venv
source .venv/bin/activate
uv pip install .

Usage

Setup credentials

jellyfish-mcp supports two different modes for setting the Jellyfish Export API token.

The preferred method is to use keyring, which comes with jellyfish-mcp. It is the most secure and ensures credentials are stored using your operating system's preferred credential store. Set your token on your system by running the following in your shell:

uv run python -m keyring set jellyfish api_token

You will then be prompted to set a password. Paste in your API token from Jellyfish and you're good to go. You won't need to do this again.

The other option uses environment variables. If you set JELLYFISH_API_TOKEN it will be used as the credential. Many MCP clients allow passing through environment variables, so refer to your tool's documentation for best practices. In general this is less secure, and isn't recommended.

Enable PromptGuard 2

jellyfish-mcp supports using Meta's Llama PromptGuard 2 model to reduce the likelihood of prompt injections attacks. However, you must manually configure this. To do so:

Create an account on https://huggingface.co which is needed download the model.
Navigate to the PromptGuard 2 86M model: https://huggingface.co/meta-llama/Llama-Prompt-Guard-2-86M
Access Meta's terms and request access to Llama models.
Wait until you are granted access
Create a huggingface API token from https://huggingface.co/settings/tokens (a read-only token is sufficient)
Within jellyfish-mcp, run uv run llamafirewall configure and provide the token when prompted. You do not need to have it stored as a git credential.

That's it. You can safely ignore warnings about TOKENIZERS_PARALLELISM or the Together API key.

Configuration with VSCode + Copilot

Open the "Command Palette..."
Search for "MCP: Add Server..." and click it
In the dialog box that appears provide: </FULL/PATH/TO/u> --directory </ABSOLUTE/PATH/TO/jellyfish-mcp> run server.py
Give the MCP server a name
Same as part of your user or workspace settings as appropriate.
Restart VSCode

Running the Server

When you open VSCode from then on, bringing up the "Chat" window should and turning on "Agent" mode should indicate that many tools have been installed from your MCP server. You can then ask Copilot various questions like:

"What endpoints are available in the Jellyfish API?"
"Can you get a list of my organization's teams?"
"Show me the API schema"

Configuration with Claude Desktop

Create or edit your Claude Desktop configuration file at:
- MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %AppData%\Claude\claude_desktop_config.json
Find your uv installation path by running:

which uv

Add the following configuration (replace paths with your values):

{
  "mcpServers": {
    "jellyfish": {
      "command": "/FULL/PATH/TO/uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/jellyfish-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

Quit and restart Claude Desktop for the configuration changes to take effect.

Running the Server

The server will start automatically when you open Claude Desktop with the proper configuration. You can then ask Claude questions about your Jellyfish data, such as:

"What endpoints are available in the Jellyfish API?"
"Can you get a list of my organization's teams?"
"Show me the API schema"

Troubleshooting

If you encounter issues:

Check Claude Desktop logs:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Verify your API token is correct and has the necessary permissions
Ensure your Jellyfish instance is accessible from your machine
Check that the paths in your Claude Desktop config are absolute and correct

License

This code is distributed under the MIT license. See: LICENSE.