# Chuck Norris MCP

> Chuck Norris MCP provides random jokes, category browsing, and full-text search access for Chuck Norris facts. Use your AI agent to pull in unexpected humor or test API connectivity during long coding sessions without needing complex keys.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** chuck-norris, jokes, humor, entertainment, api-demo

## Description

Need a break from the codebase? This connector gives your agent direct access to the official database of Chuck Norris jokes. You can ask it for a random joke instantly, grab a list of all available topics—like 'dev' or 'science'—or search through the whole thing for specific keywords. It’s pure utility for testing connectivity or just needing a quick laugh. Developers often use this kind of fun tool to check if their agent is talking to external services correctly; it’s perfect for that. By connecting Chuck Norris via Vinkius, you get reliable access to joke data right alongside your core business logic tools.

## Tools

### list_categories
Gets a full list of all available categories for the jokes.

### get_random_joke
Retrieves a random Chuck Norris joke, with the option to narrow it down by category.

### search_jokes
Searches the entire joke database using specific keywords or phrases.

## Prompt Examples

**Prompt:** 
```
Tell me a random Chuck Norris joke.
```

**Response:** 
```
Chuck Norris doesn't wear a watch. He decides what time it is.
```

**Prompt:** 
```
What are the available categories for Chuck Norris facts?
```

**Response:** 
```
I've retrieved the categories for you. You can choose from: animal, career, celebrity, dev, explicit, fashion, food, history, money, movie, music, political, religion, science, sport, and travel.
```

**Prompt:** 
```
Search for Chuck Norris jokes about 'Google'.
```

**Response:** 
```
I found a few! One of them is: 'Chuck Norris doesn't search for things on Google, Google searches for things on Chuck Norris.'
```

## Capabilities

### Get Random Jokes
Your agent fetches a random Chuck Norris joke, optionally filtered by a specific topic.

### List Joke Categories
It retrieves the complete list of all available categories for jokes (e.g., food, movie, career).

### Search Jokes by Keyword
You can search the entire joke database using specific keywords or phrases.

## Use Cases

### Prototyping a Fun Feature
A product manager needs to demo the 'fun' side of an agent. They ask their agent to run `list_categories` first, then use that list to tell the agent what kind of joke they want, like calling `get_random_joke` with the category='movie'.

### Checking Agent Reliability
A QA engineer is verifying tool-calling logic. They run a loop, repeatedly calling `get_random_joke` to ensure the agent handles rate limiting or varied data formats correctly.

### Debugging Connectivity
A developer's main feature fails mysteriously. Before diving into complex logs, they call `search_jokes` with a simple query like 'error code' to confirm basic external API access works when everything else is failing.

## Benefits

- Test API connectivity instantly. Instead of using a dummy endpoint, call `get_random_joke` to confirm your agent can talk to external services live.
- Quickly scope out possibilities with `list_categories`. You don't know what topics are available? This tool shows you everything—from 'food' to 'history.'
- Need a joke about something specific, like programming or sci-fi? Use `search_jokes` to find facts containing those exact keywords.
- Keeps the team morale up. When debugging late at night, calling this MCP is a reliable way to break the tension without leaving your IDE.
- It's perfect for demos. You can show off complex agent workflows by having it call `list_categories` then use that output in another tool call.

## How It Works

The bottom line is: you ask for humor using simple commands, and this MCP handles getting the data back.

1. Subscribe to this MCP on Vinkius. No API keys are needed for this public service.
2. Ask your AI client (Claude, Cursor, etc.) to perform a joke task in natural language.
3. The agent uses the appropriate tool and returns the requested Chuck Norris fact or list.

## Frequently Asked Questions

**Can I get a Chuck Norris joke specifically about developers or coding?**
Yes! Use the `get_random_joke` tool and specify 'dev' as the category. The agent will fetch a random fact tailored to the software engineering world.

**How can I see all the different topics available for jokes?**
You can use the `list_categories` tool. It will return a full list of supported categories such as 'science', 'money', 'fashion', and more.

**Is it possible to find jokes containing a specific word like 'roundhouse'?**
Absolutely. Use the `search_jokes` tool with your desired keyword in the 'query' parameter to find all matching facts in the database.

**Do I need an API key to use get_random_joke?**
No. This MCP connects to a public service, so you don't need complex credentials or private keys. Just connect your AI client and let it call the tool.

**How do I filter categories when using get_random_joke?**
You simply pass the desired category name as an optional argument in your tool call. For instance, passing 'movie' ensures you receive a random joke specific to that theme.

**What happens if search_jokes doesn't find any results?**
The tool handles this gracefully. If no jokes match your query, it returns an empty data set or a clear message indicating zero hits. Your agent can then act on that status.

**What is the expected output format from search_jokes?**
The results are delivered in structured JSON data. This includes both the joke text and necessary metadata, making it easy for your AI client to parse and use immediately.

**Are there rate limits when calling list_categories?**
While specific throttling policies depend on Vinkius hosting, assume standard public API usage guidelines. If you exceed the limit, your agent will receive a clear error code to manage retries.