How do I use yowes-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@yowes-mcp Generate a teacher ID for a US teacher" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

yowes-mcp

by hirotomasato

Overview Schema Source Related Servers Discussions Admin

Python

Local

Yowes — Canva Education Document Generator

Headless MCP server that generates teacher verification documents — employment letters, teacher ID cards, teaching licenses, payslips, and more — across 13 countries.

License: MIT Python MCP Platform

Portable, self-contained, and installable anywhere.

Related MCP server: paeg-teaching-materials

Sample outputs

Documents are rendered as high-resolution PNGs. Examples generated by this tool:

Teacher ID (US)	Employment letter (US)

Teacher ID (UK)	Employment letter (UK)

Features

Headless MCP server — document generation exposed as agent-callable tools over stdio.
13 countries, each with its own document types and local conventions.
Real school databases with street addresses, districts, and contact info.
Consistent profile photos per person — hash-based selection from a bundled, gender-aware photo pool.
Cross-platform fonts — DejaVu Sans bundled; no system-font dependency.
Packaged & portable — ships as a self-contained wheel (code + photos + fonts) installable with one command.

Supported countries

Code	Country	Document types
`uk`	United Kingdom	employment_letter, teacher_id, teaching_license
`us`	United States	employment_letter, teacher_id, teaching_license
`france`	France	installation_statement, iprof_screenshot, bylaws_extract, teaching_certificate
`netherlands`	Netherlands	employment_contract, teacher_registration, duo_declaration, school_id
`indonesia`	Indonesia	payslip, teaching_experience_letter, nuptk_card, appointment_letter
`australia`	Australia	signed_school_letter, school_id, teaching_license
`canada`	Canada	oct_card, teaching_license, signed_school_letter
`spain`	Spain	teaching_id, signed_school_letter, employment_contract
`argentina`	Argentina	payslip, employment_certificate, signed_school_letter
`slovakia`	Slovakia	payslip, employment_letter, signed_school_letter
`mexico`	Mexico	teaching_id, signed_school_letter, employment_certificate
`philippines`	Philippines	teaching_id, employment_certificate, teaching_license
`thailand`	Thailand	payslip, letter_of_employment

Requirements

Python 3.10+
Dependencies (installed automatically): Pillow, mcp

Installation

From the built wheel

pip install dist/yowes_doc_generator-0.1.0-py3-none-any.whl

From source (editable)

pip install -e .

Via uv

uvx --from . yowes-mcp

Usage — MCP server

The server speaks MCP over stdio — the transport used by most agent runtimes (Hermes, Claude Desktop, and any MCP client). Connect it, discover the tools, then call them.

Step 1 — Install & verify

# from the built wheel
pip install dist/yowes_doc_generator-0.1.0-py3-none-any.whl

# or editable from source
pip install -e .

Verify the install and that bundled assets resolve:

python -c "from countries.utils import load_font, get_profile_photo; \
print(load_font(30).getname()); print(get_profile_photo((280,340), person_id='x', gender='Male') is not None)"
# ('DejaVu Sans', 'Book')   <-- bundled font, not system
# True                      <-- bundled photo found

Step 2 — Run the server

# After install:
yowes-mcp

# Or from source:
python mcp_server.py

It blocks and waits for MCP requests over stdin/stdout — don't run it as a foreground terminal app expecting prompts.

Step 3 — Register in your agent runtime

Point your MCP client at the yowes-mcp command:

{
  "mcpServers": {
    "yowes": {
      "command": "yowes-mcp",
      "args": []
    }
  }
}

If yowes-mcp isn't on your PATH, use the absolute path to your interpreter and module instead:

{
  "mcpServers": {
    "yowes": {
      "command": "/path/to/python",
      "args": ["-m", "mcp_server"]
    }
  }
}

Tools

Tool	Description
`list_countries_tool`	List available countries, display names, and their document types.
`list_schools(country)`	List all schools for a country code.
`generate_documents(...)`	Render one or more documents to PNG and return their paths.

`list_countries_tool()`

No arguments. Returns one result item per country — { code, name, document_types }. (Because a list return is split into one MCP content item per entry, iterate content to see them all.)

`list_schools(country: str)`

country (required) — country code from list_countries_tool (e.g. "us").
Returns one result item per school — { name, address, town, postcode, state, phone, lea }. Iterate content to see them all.

`generate_documents(...)`

Parameter	Type	Required	Default	Description
`country`	string	✅	—	Country code (e.g. `"us"`, `"uk"`).
`first_name`	string	✅	—	Teacher's first name.
`last_name`	string	✅	—	Teacher's last name.
`school_name`	string	✅	—	Exact or partial school name (matched against that country's school list).
`position`	string	✅	—	Teaching position/title.
`date_of_birth`	string	✅	—	DOB string, printed on the teacher ID (e.g. `"12/05/1988"`).
`gender`	string	—	`"Random"`	`"Random"`, `"Male"`, or `"Female"` — selects the profile-photo pool.
`document_types`	string[]	—	all types	Which documents to render, e.g. `["employment_letter", "teacher_id"]`.
`output_dir`	string	—	`output/`	Where to save PNGs (relative to the server's working dir).

Returns { country, school, document_types, files, count, output_dir } — files are absolute PNG paths.

Connect from a Python client

Minimal working client (requires pip install mcp):

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(command="yowes-mcp", args=[])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            countries = await session.call_tool("list_countries_tool", {})
            # A list return is split into one content item per entry:
            for item in countries.content:
                print(item.text)

            res = await session.call_tool("generate_documents", {
                "country": "us",
                "first_name": "John",
                "last_name": "Smith",
                "school_name": "Valley High",
                "position": "Head of Science Department",
                "date_of_birth": "12/05/1988",
                "gender": "Male",
            })
            print(res.content[0].text)

asyncio.run(main())

Typical agent workflow

Call list_countries_tool to see what's available.
Call list_schools("us") to pick a real school.
Call generate_documents(...) with the chosen country, school, and person details.
Read the returned PNG paths and use the files.

Generated PNGs are written to output/ (or the output_dir you pass).

Legacy GUI

A tkinter (CustomTkinter) GUI is still available for manual use. The core generation logic is shared.

python main_gui.py        # on Windows, use run.bat (sets TCL_LIBRARY)

The MCP server is the primary, headless interface. The GUI is optional and not required for the skill.

Project structure

yowes/
├── countries/            # Document generation core (package)
│   ├── base.py           # CountryGenerator ABC (contract)
│   ├── utils.py          # Fonts, profile photos, shared helpers
│   ├── foto/             # Bundled profile photos (package data)
│   ├── fonts/            # Bundled DejaVu fonts (package data)
│   └── <country>/        # One package per country
├── mcp_server.py         # MCP server exposing tools
├── main_gui.py           # Legacy tkinter GUI
├── docs/examples/        # Sample rendered documents
├── pyproject.toml        # Packaging, deps, entry point
├── output/               # Generated documents (git-ignored)
└── run.bat               # Windows GUI launcher

Adding a new country

Create countries/<code>/__init__.py with a class inheriting countries.base.CountryGenerator.
Implement the abstract methods: get_country_name, get_country_code, get_schools_data, get_first_names, get_last_names, get_positions, get_document_types, generate_document.
Register it in countries/__init__.py via register_country("<code>", <Name>Generator).
Optionally add a display label in main_gui.py (get_country_list / on_country_change).

The new country is automatically picked up by the MCP list_countries_tool and list_schools.

Contributors

Masanto — author & maintainer

License

Available Tools

3 tools

generate_documentsA

Generate teacher verification documents (employment letter, teacher ID, teaching license).

Args: country: Country code from list_countries (e.g. 'us', 'uk'). first_name / last_name: The teacher's name. school_name: Exact or partial school name (matched against that country's school list). position: Teaching position/title. date_of_birth: Display date of birth string (shown on the teacher ID). gender: 'Random', 'Male', or 'Female' — selects which photo pool is used. document_types: Which documents to render. Omit for all. e.g. ['employment_letter', 'teacher_id']. output_dir: Where to save PNGs (relative to project root). Defaults to 'output'.

Returns: Dict with 'files' (absolute paths), 'count', and 'output_dir'.

ParametersJSON Schema

Name	Required	Default
`gender`	No	Random
`country`	Yes
`position`	Yes
`last_name`	Yes
`first_name`	Yes
`output_dir`	No
`school_name`	Yes
`date_of_birth`	Yes
`document_types`	No

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does well: it states that PNGs are saved, output_dir is relative to project root, gender selects a photo pool, and the return value is a dict with files/count/output_dir. Minor gaps remain around overwrite behavior and directory creation, but the key behavioral profile is disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is organized into a one-line summary followed by a clean Args list and a Returns line. Every sentence contributes necessary behavior or parameter information; there is no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter tool with no annotations and no output schema, the description is remarkably complete: it covers every parameter, the output format, the file type, defaults, and the relationship to sibling list tools. An agent has enough information to call the tool correctly with minimal risk.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so every parameter must be explained in the description, and it is: country is tied to list_countries, school_name is matched against a school list, date_of_birth appears on the teacher ID, gender selects photo pools, and document_types can be omitted for all. It even adds defaults beyond the schema, such as output_dir defaulting to 'output'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Generate teacher verification documents' and lists the three concrete document types (employment letter, teacher ID, teaching license). It also references sibling tools by name ('list_countries', 'school list'), so an agent can distinguish this generation tool from the list/helper tools without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear usage context: country codes should come from list_countries, school_name is matched against the country's school list, and document_types can be omitted for all. It does not explicitly say when not to use the tool, but the prerequisites and relationship to the sibling data-lookup tools are clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_countries_toolA

List all available countries, their display names, and the document types each can generate.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the burden of explaining behavior. It clearly states the returned data (countries, display names, document types) and 'List' implies a read-only operation, though it does not explicitly state side effects or limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence with no filler; the core action and output are front-loaded and every clause adds information. It is appropriately minimal and well structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple, has no parameters, and has an output schema, so the description provides sufficient information for an agent to invoke it. It could mention how this list relates to generate_documents (e.g., as a prerequisite), but that is not essential to making the call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so no parameter guidance is needed; the description and empty schema align perfectly. Baseline 4 for zero-parameter tools is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('all available countries') and specifies exactly what the output includes (display names and document types). This makes the tool's purpose immediately clear and distinguishes it from siblings like list_schools (different resource) and generate_documents (different action).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit statement of when to use this tool versus list_schools or generate_documents. The intended use is implied by the name and description, but the description does not name alternatives or provide exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_schoolsA

List all schools for a given country code (e.g. 'us', 'uk'). Each entry has name/address/town/postcode/state/phone/lea.

ParametersJSON Schema

Name	Required	Description	Default
`country`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the behavioral burden. It clearly conveys a read-only listing operation and describes entry fields, but it does not address invalid country codes, case sensitivity, or pagination behavior. Adequate for a simple list, but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The action and required input are front-loaded, and the output entry shape is summarized in a compact, useful way.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with an output schema, the description is nearly complete: it specifies what the tool does, what input is expected, and what each output entry contains. Missing behavior for invalid or unknown country codes is a minor gap given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema only provides a bare 'country' string with 0% coverage, so the description must add meaning. It does so by clarifying the value should be a country code ('us', 'uk') rather than a full country name. It could specify allowed formats more precisely, but the guidance is meaningful.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action ('List all schools') and resource (schools) with a clear input condition (country code) and example values. It is obviously distinct from siblings list_countries_tool and generate_documents.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool: provide a country code to get schools. However, it does not explicitly mention alternatives, such as using list_countries_tool to discover valid codes, or state when this tool should not be used.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv0.1.0Sep 19, 2026
- First observedgenerate_documents
- First observedlist_countries_tool
- First observedlist_schools

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored 2026-09-19 06:40 across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: listing countries, listing schools for a country, and generating documents. There is no overlap or ambiguity between them.

Naming Consistency4/5

Two tools follow a clean verb_noun pattern (list_schools, generate_documents), but list_countries_tool has an inconsistent '_tool' suffix. Minor deviation from an otherwise consistent naming style.

Tool Count5/5

Three tools is well-scoped for the server's purpose: discovery of countries, discovery of schools, and document generation. Each tool is necessary and none feel redundant or excessive.

Completeness5/5

The tool surface covers the full workflow: list available countries/document types, list schools for a country, then generate teacher verification documents. There are no obvious missing operations for this focused domain.

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

BizVerify A
co.bizverify
KYB for AI agents: verify business registrations from MCP clients.
Security Legal & Compliance
92
AskAIs AI Receipt Generator A
io.github.MiniCodeTeam
Generate professional receipt PDFs and structured receipt data with AI-ready MCP tools.
File Systems Workplace & Productivity
421
RESET Verifica B
com.resetparatodos
Deterministic Mexican/LatAm verification + sanctions & PEP screening for AI agents. Pay via x402.
Finance Legal & Compliance Payments & Billing
301
superdocs
app.superdocs
AI document editing for agents: draft, edit, export .docx/PDF. 37 MCP tools; agent self-signup.
Workplace & Productivity Text Summarization
21

Related MCP Servers

Enterprise Procurement MCP
ERP Systems Finance RAG Systems
kendrickjr
F
license
Not graded
quality
B
maintenance
Enables AI-powered procurement policy compliance, document generation, supplier management, budget verification, and analytics through standardized MCP tools.
Updated 3 months ago (2026-07-04 19:58 UTC)
-
paeg-teaching-materials
Education & Learning Tools App Automation
Golden2002
A
license
Not graded
quality
A
maintenance
Enables AI agents to generate teaching materials such as PPTs, handouts, lecture scripts, mind maps, teaching video storyboards, and Manim math animations, plus run quality checks and language normalization through 15 MCP tools.
Updated 22 days ago (2026-08-30 01:16 UTC)
MIT
gstinapi-mcp
Government Data Legal & Compliance Open Data
CsoftTarun
A
license
A
quality
C
maintenance
Enables live GSTIN verification, GST return and compliance history lookup, HSN/SAC code searches, and MCA company registry queries through MCP clients.
Updated 25 days ago (2026-08-27 13:04 UTC)
10
33 npm
MIT
DocumentMCP Server
File Systems Workplace & Productivity
xdelmo
F
license
Not graded
quality
B
maintenance
Enables LLMs to read and edit mock documents through custom MCP tools, resources, and prompts, allowing natural-language queries and modifications to document contents.
Updated 22 days ago (2026-08-30 11:44 UTC)
-

Yowes — Canva Education Document Generator

Table of Contents

Sample outputs

Features

Supported countries

Requirements

Installation

From the built wheel

From source (editable)

Via uv

Usage — MCP server

Step 1 — Install & verify

Step 2 — Run the server

Step 3 — Register in your agent runtime

Tools

list_countries_tool()

list_schools(country: str)

generate_documents(...)

Connect from a Python client

Typical agent workflow

Legacy GUI

Project structure

Adding a new country

Contributors

License

Available Tools

Output Schema

Output Schema

Tool Schema Changelog

Resources

Related MCP Connectors

Related MCP Servers

`list_countries_tool()`

`list_schools(country: str)`

`generate_documents(...)`