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.

Once you have the Jellyfish MCP connected, you can ask questions about your Jellyfish data, such as:

"What were our company metrics in December 2025?"
"Can you get a list of my organization's teams?"
"What are the unlinked pull requests for the last month?"

Tools and Resources

The server provides several tools for interacting with the Jellyfish API. Each tool corresponds to a specific Jellyfish API endpoint and allows you to retrieve or search for data as described in the API.

General

get_api_schema - Retrieves the complete API schema with all available API endpoints

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

DevEx

devex_insights_by_team

Metrics

company_metrics
person_metrics
team_metrics
team_sprint_summary
unlinked_pull_requests

People

list_engineers
search_people

Teams

list_teams
search_teams

Setup - Step 1: Collect API Tokens

Jellyfish Setup (required): Generate an API token from your Jellyfish instance

Go to the API Export tab on the Data Connections page.
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 and paste it when prompted.

PromptGuard Setup (optional): Generate an API token for prompt injection mitigation

jellyfish-mcp supports using Meta's Llama PromptGuard 2 model to reduce the likelihood of prompt injections attacks. To set it up, follow these steps.

Create an account on Hugging Face.
Navigate to the PromptGuard 2 86M model.
Accept Meta's terms and request access to Llama models.
Wait until you are granted access.
Create a Hugging Face API token at Hugging Face settings that is a fine-grained token with Make calls to Inference Providers permissions.
Copy the token and paste it when prompted.

Setup - Step 2: Connect to Host Applications

There are three different ways to connect to the Jellyfish MCP: A) Claude Desktop Extension, B) Docker, or C) Locally. The easiest and recommended approach is with Claude Desktop using the Desktop Extension. For all other host applications (Claude Code, VSCode, Cursor, etc), you can use either Docker or Local Setup. Docker is recommended since it doesn't require Node.js or managing dependencies. Use the local setup if you want more control or want to modify the source code.

It's important to know about the environment variables since you will need to configure them when setting up the Jellyfish MCP. JELLYFISH_API_TOKEN is the only required environment variable. The remaining three are optional and correspond to PromptGuard, which uses Meta's Llama PromptGuard 2 model to help mitigate prompt injection attacks. If you choose not to use PromptGuard, simply remove the environment variables from your .claude.json/mcp.json file.

Variable	Description	Required	Default
`JELLYFISH_API_TOKEN`	Your Jellyfish API token.	Yes	-
`HUGGINGFACE_API_TOKEN`	Your Hugging Face API token. If not provided, PromptGuard is disabled and data is always returned.	No	-
`MODEL_AVAILABILITY`	Controls behavior when PromptGuard cannot be reached (service unavailable, timeout, or invalid token). Set to `true` to allow data if PromptGuard cannot be reached. Set to `false` to block data until PromptGuard can verify response.	No	`false`
`MODEL_TIMEOUT`	How long to wait for the PromptGuard model to respond, in seconds.	No	`10`

Installation - Option A: Claude Desktop Extension Setup

Download the jellyfish-mcp.mcpb extension from the Releases page by clicking on the file name.
Once downloaded, double click the file.
If the Claude Desktop application doesn't open automatically, open it manually.
Follow the instructions and enter your Jellyfish API token (required) and Hugging Face API token (optional).
That's it!

Installation - Option B: Docker Setup

Docker runs the MCP server in an isolated container, so you don't need to install Node.js or manage dependencies on your machine.

Prerequisites: Docker

Claude Code:

Run the following command in your terminal:

claude mcp add --transport stdio jellyfish-mcp -- docker run -i --rm --pull always -e JELLYFISH_API_TOKEN -e HUGGINGFACE_API_TOKEN -e MODEL_AVAILABILITY -e MODEL_TIMEOUT jellyfishco/jellyfish-mcp:latest

Open the .claude.json file that was modified and add the env block to the jellyfish-mcp entry:

"mcpServers": {
  "jellyfish-mcp": {
    "command": "docker",
    "args": [
      "run", "-i", "--rm",
      "--pull", "always",
      "-e", "JELLYFISH_API_TOKEN",
      "-e", "HUGGINGFACE_API_TOKEN",
      "-e", "MODEL_AVAILABILITY",
      "-e", "MODEL_TIMEOUT",
      "jellyfishco/jellyfish-mcp:latest"
    ],
    "env": {
      "JELLYFISH_API_TOKEN": "your_jellyfish_token",
      "HUGGINGFACE_API_TOKEN": "your_huggingface_token",
      "MODEL_AVAILABILITY": "true_or_false",
      "MODEL_TIMEOUT": "seconds"
    }
  }
}

Run claude mcp list to verify the server is connected.

VSCode:

Open the Command Palette... (View → Command Palette... on macOS)
Search for MCP: Add Server... and press Enter
Select Docker Image and press Enter
Enter jellyfishco/jellyfish-mcp as the image name and press Enter
Select Allow and press Enter
Enter your Jellyfish API token and press Enter
Optionally, enter your Hugging Face API token and press Enter
Optionally, enter true or false for model availability and press Enter
Optionally, enter an integer (seconds) for model timeout and press Enter
Enter jellyfish-mcp as the server ID and press Enter

Cursor:

Go to Cursor Settings (Cursor → Settings... → Cursor Settings on macOS)
Go to Tools & MCP and select Add Custom MCP
Add the following to mcp.json:

{
  "mcpServers": {
    "jellyfish-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--pull", "always",
        "-e", "JELLYFISH_API_TOKEN",
        "-e", "HUGGINGFACE_API_TOKEN",
        "-e", "MODEL_AVAILABILITY",
        "-e", "MODEL_TIMEOUT",
        "jellyfishco/jellyfish-mcp:latest"
      ],
      "env": {
        "JELLYFISH_API_TOKEN": "your_jellyfish_token",
        "HUGGINGFACE_API_TOKEN": "your_huggingface_token",
        "MODEL_AVAILABILITY": "true_or_false",
        "MODEL_TIMEOUT": "seconds"
      }
    }
  }
}

Installation - Option C: Local Setup

Run the MCP server directly on your machine. Use this if you want more control or want to modify the source code.

Prerequisites: Node.js (v18 or later)

Clone and install:

git clone https://github.com/Jellyfish-AI/jellyfish-mcp.git
cd jellyfish-mcp
npm install

Claude Code:

Run the following command in your terminal:

claude mcp add --transport stdio jellyfish-mcp -- node /ABSOLUTE/PATH/TO/jellyfish-mcp/server/index.js

Open the .claude.json file that was modified and add the env block to the jellyfish-mcp entry:

"mcpServers": {
  "jellyfish-mcp": {
    "type": "stdio",
    "command": "node",
    "args": [
      "/ABSOLUTE/PATH/TO/jellyfish-mcp/server/index.js"
    ],
    "env": {
      "JELLYFISH_API_TOKEN": "your_jellyfish_token",
      "HUGGINGFACE_API_TOKEN": "your_huggingface_token",
      "MODEL_AVAILABILITY": "true_or_false",
      "MODEL_TIMEOUT": "seconds"
    }
  }
}

Run claude mcp list to verify the server is connected.

VSCode:

Open the Command Palette... (View → Command Palette... on macOS)
Search for MCP: Add Server... and press Enter
Select Command (stdio)
Enter node /ABSOLUTE/PATH/TO/jellyfish-mcp/server/index.js and press Enter
Enter jellyfish-mcp as the server name and press Enter
Open the generated config file (.vscode/mcp.json) and add the env block:

{
  "servers": {
    "jellyfish-mcp": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/jellyfish-mcp/server/index.js"
      ],
      "env": {
        "JELLYFISH_API_TOKEN": "your_jellyfish_token",
        "HUGGINGFACE_API_TOKEN": "your_huggingface_token",
        "MODEL_AVAILABILITY": "true_or_false",
        "MODEL_TIMEOUT": "seconds"
      }
    }
  },
  "inputs": []
}

Cursor:

Go to Cursor Settings (Cursor → Settings... → Cursor Settings on macOS)
Go to Tools & MCP and select Add Custom MCP
Add the following to mcp.json (with the appropriate paths):

{
  "mcpServers": {
    "jellyfish-mcp": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/jellyfish-mcp/server/index.js"
      ],
      "env": {
        "JELLYFISH_API_TOKEN": "your_jellyfish_token",
        "HUGGINGFACE_API_TOKEN": "your_huggingface_token",
        "MODEL_AVAILABILITY": "true_or_false",
        "MODEL_TIMEOUT": "seconds"
      }
    }
  }
}

Troubleshooting

If you encounter issues:

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 config files are absolute and correct
For Docker, ensure Docker is running (docker info to check)

License

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

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
.github/workflows		.github/workflows
assets		assets
server		server
tests		tests
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
manifest.json		manifest.json
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Jellyfish MCP Server

Overview

Tools and Resources

General

Allocations

Delivery

DevEx

Metrics

People

Teams

Setup - Step 1: Collect API Tokens

Jellyfish Setup (required): Generate an API token from your Jellyfish instance

PromptGuard Setup (optional): Generate an API token for prompt injection mitigation

Setup - Step 2: Connect to Host Applications

Installation - Option A: Claude Desktop Extension Setup

Installation - Option B: Docker Setup

Claude Code:

VSCode:

Cursor:

Installation - Option C: Local Setup

Claude Code:

VSCode:

Cursor:

Troubleshooting

License

About

Uh oh!

Releases 3

Uh oh!

Contributors 5

Uh oh!

Languages

License

Jellyfish-AI/jellyfish-mcp

Folders and files

Latest commit

History

Repository files navigation

Jellyfish MCP Server

Overview

Tools and Resources

General

Allocations

Delivery

DevEx

Metrics

People

Teams

Setup - Step 1: Collect API Tokens

Jellyfish Setup (required): Generate an API token from your Jellyfish instance

PromptGuard Setup (optional): Generate an API token for prompt injection mitigation

Setup - Step 2: Connect to Host Applications

Installation - Option A: Claude Desktop Extension Setup

Installation - Option B: Docker Setup

Claude Code:

VSCode:

Cursor:

Installation - Option C: Local Setup

Claude Code:

VSCode:

Cursor:

Troubleshooting

License

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 3

Uh oh!

Contributors 5

Uh oh!

Languages