# JokeAPI MCP

> JokeAPI provides programmatic access to thousands of jokes for content auditing. This MCP lets your agent audit available joke categories, pull a random hit instantly, or filter results by specific flags like 'nsfw' or 'religious'. It’s built for anyone who needs reliable, categorized humor data without manual searching.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** rest-api, humor, content-curation, api-testing, entertainment-data

## Description

Building entertaining apps requires more than just writing code; you need fresh content that hits the mark. This MCP lets your agent handle the entire process of joke research and auditing. You can talk to your client—your AI agent—and ask it to find exactly what you need, whether that's a random laugh or a highly specific theme like 'Programming'. It checks which categories are available, pulls jokes based on those themes, and even audits content safety by checking flags for sensitive topics. If you use Vinkius, this MCP slots right into your existing setup, letting your agent manage all the data retrieval in one conversation. You get clean, structured joke data without ever having to touch a humor portal.

## Tools

### check_api_status
Checks if the entire JokeAPI service is running and ready to accept requests.

### get_jokes_by_category
Retrieves jokes that belong specifically to a listed category, like 'Programming' or 'Pun'.

### get_random_joke
Pulls any joke from the entire database immediately.

### list_joke_categories
Displays a full list of every available joke theme in the system.

### list_joke_blacklist_flags
Lists all content flags you can use to filter out sensitive material, like 'nsfw' or 'religious'.

## Prompt Examples

**Prompt:** 
```
Get a random 'Programming' joke using JokeAPI.
```

**Response:** 
```
I've retrieved a programming joke! It's currently identified as: "[Setup]... [Delivery]". Would you like to see another one or a different category like 'Pun'?
```

**Prompt:** 
```
List all available joke categories.
```

**Response:** 
```
I've scanned the category catalog. There are 6 main categories available, including 'Programming', 'Misc', 'Dark', 'Pun', 'Spooky', and 'Christmas'. I can help you retrieve a random joke for any of these specific themes.
```

**Prompt:** 
```
What are the content flags for filtering jokes?
```

**Response:** 
```
I've retrieved the blacklist flags! You can filter jokes by 'nsfw', 'religious', 'political', 'racist', 'sexist', and 'explicit'. I can assist you with an audit of jokes that avoid any of these specific markers.
```

## Capabilities

### Verify service status
You confirm that the JokeAPI connection is live and operational before starting any content pull.

### List all themes
Your agent shows you every possible joke category, like 'Pun' or 'Dark', so you know what kind of humor to expect.

### Pull a random joke
You instantly get any joke pulled from the database without specifying a theme or type.

### Filter by specific category
The agent pulls jokes that fit one particular style, like only 'Spooky' or 'Misc' material.

### Audit content filters
You check the available blacklisting flags (e.g., 'political', 'sexist') to ensure your content stays safe and clean.

## Use Cases

### Rolling out a new social widget
A content manager needs 10 fresh jokes for a product launch announcement. Instead of spending hours in multiple joke databases, they ask their agent to use `get_random_joke` ten times and then run `list_joke_blacklist_flags` to verify that none of the selected jokes trigger sensitive filters.

### Developing a specialized quiz feature
An app developer needs to build a quiz only focused on programmer humor. They first use `list_joke_categories` to confirm 'Programming' exists, then call `get_jokes_by_category` to pull the exact content needed for the quiz.

### Auditing an existing knowledge base
A linguist wants to check if their joke data pool contains any material flagged as 'political' or 'racist'. They run `list_joke_blacklist_flags` and then use the flags list in conjunction with other tools to ensure compliance.

## Benefits

- Content variety is always one prompt away. Instead of manually searching for fresh material, use the `get_random_joke` tool to get an immediate hit in your workflow.
- Maintain content safety by checking flags first. Use `list_joke_blacklist_flags` to audit which topics are prohibited before you ever write a line of code.
- Target specific humor types with precision. When you need a certain feel, use the `get_jokes_by_category` tool instead of guessing or accepting whatever random joke comes along.
- See everything available in one go. Start by running `list_joke_categories` to map out all possible themes for your application's feature set.
- Ensure reliability before you deploy. Run `check_api_status` anytime to confirm the data source is operational, preventing workflow errors.

## How It Works

The bottom line is you get structured joke data and content audits directly in your chat window.

1. Subscribe to this MCP via Vinkius.
2. Connect your agent client (like Cursor or Claude).
3. Tell your agent what you need—for example, 'Find me a random joke' or 'List all available categories.' The tool handles the rest.

## Frequently Asked Questions

**How do I check if JokeAPI is actually working?**
Run `check_api_status`. This tool confirms that the entire service connection is live and ready for any data retrieval or auditing tasks you plan to run.

**What are all the joke themes available with list_joke_categories?**
Use `list_joke_categories` to get a full inventory. This tells you every theme, from 'Pun' to 'Misc', so you can build out your content plan.

**Can JokeAPI help me filter for bad jokes?**
You manage this using `list_joke_blacklist_flags`. Running this tool shows all the available flags (like 'nsfw' or 'political') so you can audit your content against them.

**I just need one joke right now, what do I use?**
Use `get_random_joke`. This tool pulls a single hit immediately, bypassing the need to specify any category or theme for quick testing.

**Do I need an API key to use any of these tools, like list_joke_categories?**
No, you don't. This MCP service requires no API keys or credentials for access. You simply connect your AI client to Vinkius and the agent handles all communication automatically.

**What should I do if get_jokes_by_category returns an empty list?**
If a joke category yields no results, your agent will report it. You can then run list_joke_categories to check the spelling of the theme or try getting a random joke instead.

**What is the best workflow for finding jokes in a niche area? Should I use list_joke_categories first?**
Yes, always run list_joke_categories at the start. This confirms available themes before you attempt to retrieve content using get_jokes_by_category, preventing potential errors.

**How do I ensure jokes are clean of specific markers? Can I combine flags with other tools?**
Your agent supports this. You first use list_joke_blacklist_flags to identify constraints, then pass those restrictions when querying for a joke in a category.

**Is an API Key required for JokeAPI?**
No. JokeAPI is a free and open service. This server works out of the box without any static credentials required.

**Can I filter jokes by language?**
Yes. Use the `getRandomJoke` tool and provide the `lang` parameter (e.g., 'en' or 'de'). Your agent will return matching jokes instantly.

**Does it support setup/delivery format?**
Yes. JokeAPI provides both single-line and two-part (setup and delivery) jokes. Your agent will display them in the appropriate Markdown format.