# JokeAPI MCP

> JokeAPI gives your AI client a massive database of jokes, letting it act like a dedicated comedian. You can request single random jokes or bulk lists. Crucially, you control the content using filters for specific categories—like Programming or Pun—and safety flags to exclude NSFW, political, or religious material.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** rest-api, humor, content-generation, data-filtering, entertainment-services

## Description

This MCP connects your AI agent to a massive library of jokes written in multiple languages. Need a quick icebreaker? Ask for a random joke. Building an application that needs varied content? You can request multiple jokes at once and even summarize them to find popular themes. It's much more than just fetching randomness; you get granular control. Want only programming-related humor, or maybe something spooky for Halloween? You filter it by category. And if your app requires clean content, the safety flags let you block out any NSFW or political jokes before they reach the user. Connecting this through Vinkius means you access all these joke capabilities from one place, letting your agent handle the conversation and the data retrieval simultaneously.

## Tools

### list_joke_categories
It tells you all the available joke categories so you know what types of humor are in the database.

### get_joke
You can get one single random joke when your conversation needs a quick laugh.

### list_jokes
This tool fetches multiple jokes at once, which is useful for creating lists or bulk content.

## Prompt Examples

**Prompt:** 
```
Tell me a programming joke.
```

**Response:** 
```
Sure! Why do programmers always mix up Halloween and Christmas? Because Oct 31 equals Dec 25! Want to hear another one?
```

**Prompt:** 
```
Give me 3 safe jokes from the 'Misc' category.
```

**Response:** 
```
Retrieving 3 safe miscellaneous jokes... Here is the first one: 'I'm reading a book on anti-gravity. It's impossible to put down!' Ready for the others?
```

**Prompt:** 
```
Do you have any 'Spooky' jokes for Halloween?
```

**Response:** 
```
Fetching a spooky joke... 'Why don't ghosts like rain? Because it damps their spirits!' I can find more themed jokes if you're planning a party.
```

## Capabilities

### List available joke categories
It shows you every category of jokes available in the database (e.g., Programming, Pun, Misc).

### Retrieve a single random joke
You get one whole joke instantly, which is perfect for quick conversational replies.

### Get a list of multiple jokes
The tool returns an array of several jokes, useful when you need to populate content or run through examples.

### Filter by safety flags
You tell the system which types of offensive material (NSFW, political, etc.) to exclude from the results.

### Support multiple languages
The agent can fetch jokes in several different languages like English, German, or Portuguese.

## Use Cases

### A chat bot needs daily filler content.
The developer asks their agent, 'Give me three safe, miscellaneous jokes.' The agent uses `list_jokes` with the 'Misc' category and safety flags to populate the bot’s response, keeping engagement high.

### A team needs examples of programming humor.
The writer asks their agent to find jokes about coding. The agent calls `list_joke_categories` first to confirm 'Programming' is valid, then uses that category filter with `get_joke` to provide a relevant example.

### A social media campaign needs varied content.
The marketer asks for several lighthearted posts. The agent calls `list_jokes`, specifying the 'Pun' category and limiting it to non-offensive jokes, generating quick drafts for review.

### Testing international chat features.
A developer tests localization by asking for a joke in German. The agent uses the language support feature to retrieve the correct localized content via `get_joke`.

## Benefits

- The JokeAPI allows your agent to behave like a comedian, providing instant content for chat bots or side projects. You never have to manually source joke material again.
- You gain total control over the output. If you only want jokes about coding, use the category filters instead of pulling random stuff that might miss the mark.
- Building robust apps means managing bad inputs. The safety flags let your agent automatically filter out any content marked NSFW or political before it ever gets shown to a user.
- Need high volume? Instead of calling `get_joke` dozens of times, use `list_jokes` to fetch multiple jokes in one go, which is much more efficient for bulk data generation.
- It supports multilingual humor. You can get the AI client to handle and deliver jokes in several languages (e.g., German or Portuguese) without changing your code.

## How It Works

The bottom line is that your AI client talks to this MCP like talking to a comedian, handling all the filtering and retrieval under the hood.

1. First, subscribe to this MCP on Vinkius and connect your preferred AI client.
2. Next, ask your agent for the jokes. You can specify filters like 'Programming' or 'safe only', which tells the system exactly what you need.
3. Finally, the agent handles calling the right tool—whether it’s listing categories or fetching a joke list—and presents the clean result back to you in natural conversation.

## Frequently Asked Questions

**How do I find out what categories of jokes JokeAPI supports?**
You use the `list_joke_categories` tool. Running this tells your agent all the available topics, like Programming or Pun, so you know exactly what content is possible.

**Is JokeAPI safe for professional business apps?**
Yes, because of its built-in safety flags. You can explicitly tell it to filter out NSFW, political, and religious jokes, making the output suitable for most corporate or client-facing tools.

**What's the difference between `get_joke` and `list_jokes`?**
`get_joke` is meant for one quick joke. Use it when you need a single, immediate response. If you want to bulk-populate content or run through several examples, use `list_jokes`.

**Can JokeAPI provide jokes in multiple languages?**
Yep. The API supports fetching humor in several different languages (including German and Portuguese). Just specify the language when you make your request to your agent.

**What authentication method do I need when using `get_joke`?**
You don't need to worry about keys. This MCP uses public access, meaning you connect your agent directly without needing an API key or complex credential setup.

**Are there rate limits if I run `list_jokes` frequently?**
Yes, like any external service, the JokeAPI enforces standard usage rates. We recommend checking the Vinkius documentation for current throughput guidelines to keep your bot running smoothly.

**How do I ensure a joke fits a specific theme using `get_joke`?**
You pass the desired category (like 'Programming' or 'Pun') as an argument. This limits the output pool, ensuring your jokes are relevant to a defined topic.

**What should I do if my call to `list_jokes` returns an error?**
Most errors come down to invalid parameters or connection issues. Always check the specific response code and try simplifying your request before assuming a bug in the MCP.

**Can I get 5 jokes specifically about programming?**
Yes! Use the `list_jokes` tool and set the `category` to 'Programming' and `amount` to 5. It will return a set of developer-themed jokes.

**How do I filter out offensive jokes?**
You can use the `blacklistFlags` parameter in the tools. Specify 'nsfw,religious,political,racist,sexist,explicit' to ensure only safe jokes are returned.

**What languages are supported for jokes?**
JokeAPI supports multiple languages including English (en), German (de), Spanish (es), French (fr), and Portuguese (pt). Use the `lang` parameter to specify your choice.