Country Generator MCP server

Connect

Add the server URL to your assistant. There is no key to paste and nothing to install.

Claude Code

claude mcp add --transport http countrygenerator https://countrygenerator.com/mcp

Claude (web, desktop and mobile)

Open Settings, then Connectors, choose Add custom connector, give it a name and paste the server URL.

ChatGPT

Turn on Developer mode in the connector settings, create a connector, and paste the server URL. Choose no authentication.

Cursor

Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "countrygenerator": {
      "url": "https://countrygenerator.com/mcp"
    }
  }
}

VS Code

Add this to .vscode/mcp.json, then start the server from the file or from the MCP view:

{
  "servers": {
    "countrygenerator": {
      "type": "http",
      "url": "https://countrygenerator.com/mcp"
    }
  }
}

Clients that only run local servers

If your client can only start a local command, bridge it with mcp-remote (needs Node.js):

{
  "mcpServers": {
    "countrygenerator": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://countrygenerator.com/mcp"]
    }
  }
}

Try it

After you connect, ask in plain words. The assistant picks the tools.

• "Quiz me on African flags, hard mode."
• "Give me 10 capital questions about Asia, in German."
• "Name a country that borders Brazil." Then: "Quiz me on neighbours in Europe."
• "Which has more people: Nigeria, Brazil or Japan?"
• "Pick a random country in Oceania and tell me about it."
• "Which countries in Africa have no coastline?"

In clients that show prompts (Claude Code, VS Code and others), you can also start a quiz with the quiz_me prompt.

How a quiz works

1. The assistant calls create_quiz. Each question comes with a sealed ticket, and most come with four options (for borders you name any neighbour). The ticket holds the answer in encrypted form, so the assistant cannot read it or give it away early. Flag and outline questions carry an image_url that does not name the country either.
2. The assistant asks you one question at a time. You answer with a letter, a country or capital name in any of the seven languages, or an ISO code. Small typos are fine.
3. The assistant sends your answer to check_answer with the question's ticket and the latest score_ticket. The server says if you were right, gives the right answer with a few facts, and returns the new score.
4. Three wrong answers end the run. Each question counts once, so asking the same question again does not change the score.

The questions use the same rules as the games on this site: easy, medium and hard levels, wrong options from the same region on harder levels, and look-alike flags on hard. Scores stay in your chat. They never reach the site's leaderboards.

Example: create_quiz

Request arguments:

{ "type": "flag", "difficulty": "hard", "region": "Africa", "count": 10 }

Result (shortened; tickets are long encrypted strings):

{
  "type": "flag",
  "difficulty": "hard",
  "lives": 3,
  "how_to_play": "Ask one question at a time. ...",
  "questions": [
    {
      "number": 1,
      "prompt": "Which country does this flag belong to?",
      "options": [
        { "letter": "A", "text": "Chad" },
        { "letter": "B", "text": "Romania" },
        { "letter": "C", "text": "Andorra" },
        { "letter": "D", "text": "Moldova" }
      ],
      "ticket": "eyJpdiI6...",
      "image_url": "https://countrygenerator.com/mcp/image/eyJpdiI6..."
    }
  ],
  "play_url": "https://countrygenerator.com/flag-guesser?utm_source=mcp"
}

Example: check_answer

Request arguments (leave out score_ticket for the first question):

{ "ticket": "eyJpdiI6...", "answer": "A", "score_ticket": "eyJpdiI6..." }

Result:

{
  "correct": true,
  "correct_answer": "Chad",
  "about": { "country": "Chad", "capital": "N'Djamena", "subregion": "Middle Africa" },
  "score": { "correct": 4, "answered": 5, "lives_left": 2 },
  "game_over": false,
  "score_ticket": "eyJpdiI6..."
}

When game_over is true, the result also has a play_url to the full game on this site. For population questions, about lists the four populations, largest first.

Tools

All tools are read-only and only use the country data this site already serves. Each one is listed here exactly as the server describes it to your client.

create_quiz

Create a geography quiz

Create geography quiz questions: guess the country from its flag or outline, pick the capital, pick the most populated country, or name a neighbour. Ask the user one question at a time, then pass the user's answer and the question's ticket to check_answer. Do not guess the answer yourself, and do not reveal it before check_answer.

check_answer

Check a quiz answer

Check the user's answer to one create_quiz question. Pass the question's ticket, the user's answer exactly as given (a letter, a name or a code), and the score_ticket from the previous check_answer, if there was one. Returns whether it was correct, the right answer, facts to share in the user's language, and the new score.

random_country

Random country

Pick a random country, optionally from one continent, with its capital, flag, region, population and languages.

get_country

Country facts

Facts about one country: capital, region, population (World Bank 2024), area, languages, currencies, driving side and neighbours. Accepts a name in English, German, Spanish, French, Portuguese, Japanese or Italian, or an ISO code.

search_countries

Search countries

List countries by part of a name or capital, by continent, or landlocked only. Returns names, codes and capitals; call get_country for the full facts.

compare_population

Compare populations

Rank 2 to 4 countries by population, largest first, with World Bank 2024 figures.

get_borders

Neighbouring countries

The countries that share a land border with a country. An island nation returns an empty list.

Prompt

quiz_me

Start a geography quiz: flags, capitals, country outlines, populations or neighbours. It tells the assistant to use create_quiz and check_answer, ask one question at a time and keep the answer hidden until you reply.

Options

Languages

Every tool takes a locale for names, capitals and links. Answers are understood in all of them, whatever the quiz language.

Regions

The region parameter takes one continent: Africa, Americas, Asia, Europe, Oceania. A quiz stays inside the region you ask for. If a region cannot fill a question type (only one country in Oceania has a land border), you get fewer questions or an error, never questions from another continent.

Levels

• easy: well-known countries, wrong options from other well-known countries.
• medium (default): a wider mix, wrong options from the same region.
• hard: lesser-known countries, wrong options from the same subregion, and look-alike flags in the flag quiz (Chad and Romania, Indonesia and Monaco, and more).

Limits and errors

• Rate limits: 60 requests a minute for each client session, and 3,000 a minute for each IP address. Over a limit, the server answers HTTP 429 with a Retry-After header. A quiz uses one request to create it and one for each answer, so a person never comes near the limit.
• Quiz size: 1 to 20 questions for each create_quiz call. Call it again for more.
• Tickets expire after 24 hours. A ticket from another quiz, or one that was changed, is refused.
• Errors come back as a normal tool result with isError: true and a sentence that tells the assistant what to do next, for example "This question was already answered. Ask the next question." or "No country matches "Atlantis". Try the English name or a two-letter ISO code."

Raw protocol

The server speaks JSON-RPC 2.0 over HTTP POST. It keeps no session, so a client can call a tool without the initialize step. To test from a terminal:

curl -s https://countrygenerator.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_country","arguments":{"country":"Japan"}}}'

The result has the facts both as structuredContent and as JSON text in content, for clients that read only one of them. Use tools/list and prompts/list to read the same definitions that this page shows. A GET request that asks only for text/event-stream gets 405: the server has no event stream to offer.

Data and privacy

• The server only reads country data. It stores nothing about you or your chat, keeps no quiz state on its side (the score travels in the sealed score_ticket), and needs no account.
• The assistant sends only the tool arguments to this server, not your conversation.
• Country facts come from the mledoze/countries dataset, with corrected capitals. Populations are World Bank 2024 figures, except Taiwan and Vatican City, which keep earlier estimates. See the Terms for sources and licences, and the Privacy Policy for what our servers log.

Questions

Can the assistant cheat and tell me the answer?

Not from the quiz itself. The answer is only inside the encrypted ticket, and image links do not name the country. A model can still recognise a famous flag from the picture, the same as a person can.

Does my score count on the site's leaderboards?

No. Quizzes in your assistant are practice. To rank, play the games on this site and sign in. Every quiz ends with a link to the full game.

Is the daily challenge available?

No. The daily puzzle is shared with everyone on the site, and its answer stays on the site.

Which capital counts when a country has more than one?

The constitutional capital, the same as the games: Sucre for Bolivia, Sri Jayawardenepura Kotte for Sri Lanka, Mbabane for Eswatini.

My client does not show the flag pictures.

Some clients do not show images from tool results. The quiz still works: the assistant can describe the question, or you can open the image_url yourself.

Play on the site

Every quiz links back to the full game here, with leaderboards when you sign in: the Flag Quiz, Capitals Quiz, Country Shapes, Most Populated Country Quiz and Borders Quiz.