Skip to main content
Glama

Python 3.12+ pytest PyPI GitHub commits since latest release CodeQL Advanced OpenSSF Scorecard

Primarily to be used as a template repository for developing MCP servers with FastMCP in Python, PyMCP is somewhat inspired by the official everything MCP server in Typescript.

Components

The following components are available on this MCP server.

Tools

  1. greet

  • Greets the caller with a quintessential Hello World message.

  • Input(s)

    • name: string (optional): The name to greet. Default value is none.

  • Output(s)

    • TextContent with a UTC time-stamped greeting.

  1. generate_password

  • Generates a random password with specified length, optionally including special characters and conforming to the complexity requirements of at least one lowercase letter, one uppercase letter, and two digits. If special characters are included, it will also contain at least one such character.

  • Input(s)

    • length: integer: The length of the generated password. The value must be an integer between 8 and 64, both inclusive.

    • use_special_chars: boolean (optional): A flag to indicate whether the password should include special characters. Default value is False.

  • Output(s)

    • TextContent with the generated password.

  1. text_web_search

  • Searches the web with a text query using the Dux Distributed Global Search (DDGS).

  • Input(s)

    • query: string: The search query to fetch results for. It should be a non-empty string.

    • region: string (optional): Two letter country code followed by a hyphen and then by two letter language code, e.g., uk-en or us-en. Default value is uk-en.

    • max_results: integer (optional): Optional maximum number of results to be fetched. Default value is 10.

    • pages: integer (optional): Optional number of pages to spread the results over. Default value is 1.

  • Environment variable(s)

    • DDGS_PROXY: string (optional): Optional proxy server to use for egress web search requests.

  • Output(s)

    • TextContent with a list of dictionaries with search results.

  1. permutations

  • Calculates the number of ways to choose $k$ items from $n$ items without repetition and with order. If $k$ is not provided, it defaults to $n$.

  • Input(s)

    • n: integer: The number of items to choose from. This should be a non-zero, positive integer.

    • k: integer (optional): The number of items to choose. Default value is the value of n.

  • Output(s)

    • TextContent with number of ways to choose $k$ items from $n$, essentially ${}^{n}P_{k}$.

  1. run_python_code

  • Runs arbitrary Python code in a secure and fast interpreter using Pydantic Monty. Note that Pydantic Monty is experimental and Python language support is partial as of February 8, 2026.

  • Input(s)

    • code: string: The Python code to run.

    • inputs: dict[str, Any] (optional): A dictionary of input values for the Python code. Default value is None.

    • script_name: str (optional): The name of the script used in traceback and error messages. Default value is main.py.

    • check_types: bool (optional): A flag to indicate whether to check types. Default value is True.

    • type_definitions: str (optional): Type definitions to be used for type checking. Default value is None.

  • Output(s)

    • TextContent with the output, if any, of the Python code.

NOTE

Thepirate_summary (LLM client sampling) and vonmises_random (client elicitation) example tools have been removed. Both relied on server-initiated requests (ctx.sample() and ctx.elicit()), which SEP-2577 removed from the modern MCP protocol (2026-07-28) in favour of a stateless per-request envelope with no back-channel for the server to call back into the client. FastMCP now marks both APIs deprecated — they still function, but only on the older, handshake-era (session-based) protocol. These tools were dropped rather than kept working against a deprecated protocol era.

This does not affect the tools, resources, and prompts that remain: the underlying MCP SDK negotiates the protocol version per connection and serves both 2026-07-28+ and handshake-era clients automatically, with no code changes needed here. Only server-initiated back-channel patterns (i.e., anything using ctx.sample() or ctx.elicit()) are legacy-only. If you fork this template and want to add a tool that relies on client sampling or elicitation, be aware it will only work against clients that negotiate the older, deprecated protocol.

Related MCP server: MCP Server Example

Resources

  1. resource_logo

  • Retrieves the Base64 encoded PNG logo of PyMCP along with its SHA3-512 hash.

  • URL: data://logo

  • Output(s)

    • TextContent with a Base64EncodedBinaryDataResponse Pydantic object with the following fields.

      • data: string: The Base64 encoded PNG logo of PyMCP.

      • hash: string: The hexadecimal encoded cryptographic hash of the raw binary data, which is represented by its Base64 encoded string equivalent in data. (The hex encoded hash value is expected to be 6414b58d9e44336c2629846172ec5c4008477a9c94fa572d3419c723a8b30eb4c0e2909b151fa13420aaa6a2596555b29834ac9b2baab38919c87dada7a6ef14.)

      • hash_algorithm: string: The cryptographic hash algorithm used, e.g., sha3_512.

  1. resource_logo_svg

  • Retrieves the SVG logo of PyMCP.

  • URL: data://logo_svg

  • Output(s)

    • TextContent with a the SVG data for the PyMCP logo.

  1. resource_unicode_modulo10

  • Computes the modulus 10 of a given number and returns a Unicode character representing the result. The character is chosen based on whether the modulus is odd or even. For odd modulus, it uses the Unicode characters ❶ (U+2776), ❸ (U+2778), ❺ (U+277A), ❼ (U+277C), and ❾ (U+277E). For even modulus, it uses the Unicode characters ⓪ (U+24EA), ② (U+2461), ④ (U+2463), ⑥ (U+2465), and ⑧ (U+2467).

  • URL: data://modulo10/{number}

  • Input(s)

    • number: integer: A positive integer between 1 and 1000, both inclusive.

  • Output(s)

    • TextContent with a string representing the correct Unicode character.

Prompts

  1. code_prompt

  • Get a prompt to write a code snippet in Python based on the specified task..

  • Input(s)

    • task: string: The description of the task for which a code implementation prompt will be generated.

  • Output(s)

    • str representing the prompt.

Installation

The directory where you clone this repository will be referred to as the working directory or WD hereinafter.

Install uv. Install just. To install the project with its minimal dependencies in a virtual environment, run the following in the WD. To install all non-essential dependencies (which are required for developing and testing), replace the install target with the install-all target in the following command.

just install

Environment variables

The following environment variables can be configured.

  • PYMCP_LOG_LEVEL: Sets the Python log level for the PyMCP server. Default is INFO.

  • MCP_SERVER_TRANSPORT: Sets the FastMCP server transport type of this MCP server. Default is stdio.

  • RESPONSE_CACHE_TTL: Sets the time, in seconds, for the time-to-live (TTL) cache that can be activated for caching prompt, resource and tool responses from the server. Default value is 30. Any integer value between 0 and 86400 (i.e., one day), both inclusive, is valid. Setting it to 0 effectively disables response caching.

  • FASTMCP_HOST: Sets the host address for the FastMCP server when using network transports (e.g., streamable-http, sse). Default is localhost.

  • FASTMCP_PORT: Sets the port number for the FastMCP server when using network transports. Default is 8000.

  • ASGI_CORS_ALLOWED_ORIGINS: Sets the CORS allowed origins when the MCP server is started with a transport over HTTP. Default is ["*"].

Standalone usage

PyMCP can be started standalone as a MCP server with stdio transport by running the following. Alternatively, it can be started using streamable-http or sse transports by specifying the transport type using the MCP_SERVER_TRANSPORT environment variable.

uv run pymcp

Test with the MCP Inspector

The MCP Inspector is an official Model Context Protocol tool that can be used by developers to test and debug MCP servers. This is the most comprehensive way to explore the MCP server.

To use it, you must have Node.js installed. The best way to install and manage node as well as packages such as the MCP Inspector is to use the Node Version Manager (or, nvm). Once you have nvm installed, you can install and use the latest Long Term Release version of node by executing the following.

nvm install --lts
nvm use --lts

Following that, run the MCP Inspector and PyMCP by executing the following in the WD.

npx @modelcontextprotocol/inspector uv run pymcp

This will create a local URL at port 6274 with an authentication token, which you can copy and browse to on your browser. Once on the MCP Inspector UI, press Connect to connect to the MCP server. Thereafter, you can explore the tools available on the server.

You can, alternatively, launch the MCP inspector by running just launch-inspector.

Use it with Claude Desktop, Visual Studio, and so on

The server entry to run with stdio transport that you can use with systems such as Claude Desktop, Visual Studio Code, and so on is as follows.

{
    "command": "uv",
    "args": [
        "run",
        "pymcp"
    ]
}

Instead of having pymcp as the last item in the list of args, you may need to specify the full path to the script, e.g., WD/.venv/bin/pymcp.

Remotely hosted options

The currently available remotely hosted options are as follows.

Testing and coverage

To run the provided set of tests using pytest, execute the following in WD. To get a report on coverage while invoking the tests, run the following in WD.

just test-coverage

This will generate something like the following output.

Name    Stmts   Miss    Cover   Missing
---------------------------------------
TOTAL     214      0  100.00%

Contributing

See the Contributing guide.

License

MIT.

Available Tools

5 tools
generate_passwordGenerate PasswordA
Read-only
Inspect

Generate a random password with specified length, optionally including special characters.

ParametersJSON Schema
NameRequiredDescriptionDefault
lengthNoThe length of the password to generate (between 8 and 64 characters).
use_special_charsNoInclude special characters in the password.

TDQS

A3.8/5.0
Behavior3/5

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

The annotations declare readOnlyHint=true, so the agent knows this is a safe, non-mutating operation. The description adds that the password is random and that special characters are optional, which is useful. However, it does not disclose details like whether the password is cryptographically secure, whether it is returned in plaintext, or any side effects (e.g., logging). With annotations covering the safety profile, a 3 is appropriate.

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 a single, efficient sentence that front-loads the core action and includes the two key parameters. Every word earns its place, and there is no redundancy with the schema.

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 simple, read-only generation tool with two fully documented parameters and no output schema, the description is nearly complete. The only minor gap is that it does not state the return format (e.g., plaintext string), but the tool's simplicity and the schema coverage make this a minor omission.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents both parameters and their constraints. The description adds no additional meaning beyond what the schema provides, so the baseline 3 is correct.

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 states a specific verb ('Generate'), a clear resource ('a random password'), and the key controllable attributes ('specified length', 'optionally including special characters'). It is unambiguous and distinguishes itself from the listed siblings, none of which relate to password generation.

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: whenever a random password is needed. However, it does not explicitly state when not to use it or mention any alternatives, such as using run_python_code for custom generation logic. The context is clear enough for basic selection, but there is no explicit routing guidance.

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

greetGreetA
Read-only
Inspect

Greet the caller with a quintessential Hello World message.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNoThe optional name to be greeted.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior3/5

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

Annotations provide readOnlyHint: true, indicating a safe, read-only operation. The description adds minimal behavioral context beyond that—it only mentions the Hello World style. It does not explain the optional name parameter's effect, but that is covered by the schema. With annotations covering safety, the description adds little but does not contradict.

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 a single, concise sentence that immediately states the tool's purpose. It is front-loaded and contains no fluff.

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?

The tool is trivial with one optional parameter and a clear purpose. Given the output schema exists and annotations cover safety, the description is complete enough for an agent to call it correctly without further context.

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

Parameters3/5

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

The schema already fully documents the optional 'name' parameter with its description. The tool description adds no additional parameter information, so it does not exceed the baseline of 3 given high schema coverage.

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 clearly states the tool's function: greeting the caller with a Hello World message. The verb 'greet' and the specific 'quintessential Hello World message' make the purpose unambiguous, and the sibling tools are unrelated, so there's no confusion.

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?

The description implies the tool is for greeting scenarios, but it does not explicitly state when to use it versus alternatives. However, the sibling tools are unrelated (password generation, web search, etc.), so the purpose itself provides clear context. No explicit exclusions are given, but the simple nature of the tool makes this acceptable.

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

permutationsPermutationsB
Read-only
Inspect

Calculate the number of ways to choose k items from n items without repetition and with order.

ParametersJSON Schema
NameRequiredDescriptionDefault
kNoThe optional number of items to choose.
nYesThe number of items to choose from.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

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

Annotations declare readOnlyHint=true, so the safety profile is already known. The description adds behavioral context by specifying 'without repetition and with order,' which clarifies the counting semantics. However, it does not disclose what happens when the optional k is null or how constraints like k ≤ n are handled, leaving some behavioral gaps.

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 a single, front-loaded sentence with no filler. It directly states the operation and its key constraint, making it efficient and easy to parse. Every word contributes to the meaning.

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

Completeness2/5

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

Although an output schema exists and annotations cover read-only behavior, the description is incomplete regarding the optional k parameter. It does not explain what k=null signifies (likely permutations of all n items), nor does it address the constraint that k must be ≤ n. An agent could misinvoke the tool when k is null or when k > n without this knowledge.

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

Parameters3/5

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

Schema description coverage is 100%, so both n and k are already documented in the schema. The description rephrases the semantics ('choose k items from n items') but adds no new detail about parameter meaning, especially the null default for k. Thus, the schema carries the parameter documentation burden, making a baseline score of 3 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 clearly states the operation: 'Calculate the number of ways to choose k items from n items without repetition and with order.' This specifies the verb, resource, and the defining constraint (order matters) that distinguishes it from combinations. Sibling tools are unrelated, so no confusion.

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

Usage Guidelines2/5

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

The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or what to use when order does not matter. The only usage signal is implicit in the purpose, which is not sufficient for optimal tool selection.

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

run_python_codeRun Python CodeCInspect

Run the given Python code and return the output or error message.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYes
inputsNo
check_typesNo
script_nameNomain.py
type_definitionsNo

TDQS

C2.8/5.0
Behavior2/5

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

With no annotations, the description must fully disclose behavioral traits. It only mentions running code and returning output/error, omitting critical details like sandboxing, network access, side effects, timeouts, or security implications. For a code execution tool, this is a major gap.

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

Conciseness3/5

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

The description is concise (one sentence) and front-loaded with the primary action, but it does not add meaningful structure or detail. It is efficient but lacks substance beyond the basic statement, so it does not fully earn its place.

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

Completeness1/5

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

The tool has 5 parameters, no annotations, and no output schema. The description is far too minimal to enable correct invocation: it omits parameter semantics, return behavior, potential side effects, and any constraints. This is inadequate for a tool of this complexity.

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

Parameters1/5

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

Schema description coverage is 0%, and the description only implicitly references the 'code' parameter. It does not explain the purpose or usage of 'inputs', 'check_types', 'script_name', or 'type_definitions', leaving the agent without any guidance on how to use these parameters correctly.

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 clearly states the tool runs Python code and returns output or error. This is a specific verb+resource that distinguishes it from the sibling tools (greet, generate_password, text_web_search, permutations) which are obviously unrelated in function.

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 does not explicitly state when to use this tool versus alternatives, but the sibling tools are for distinct tasks, so usage is implied. No explicit exclusions or conditions are provided, but the context makes the choice fairly obvious.

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.

  1. 2 tool updatesv1.0.2
    • Removedpirate_summary
    • Removedvonmises_random
  2. 7 tool updatesv1.0.1
    • Changedgenerate_password1 field changed
      • addedInput schema / additionalProperties
        Added value: +false
    • Changedgreet1 field changed
      • addedInput schema / additionalProperties
        Added value: +false
    • Changedpermutations1 field changed
      • addedInput schema / additionalProperties
        Added value: +false
    • Changedpirate_summary1 field changed
      • addedInput schema / additionalProperties
        Added value: +false
    • Addedrun_python_code
    • Changedtext_web_search1 field changed
      • addedInput schema / additionalProperties
        Added value: +false
    • Changedvonmises_random1 field changed
      • addedInput schema / additionalProperties
        Added value: +false
  3. 6 tool updatesv1.0.0
    • Addedgenerate_password
    • Changedgreet3 fields changed
      • removedInput schema / properties / name / title
        Removed value: -"Name"
      • removedOutput schema / properties / result / title
        Removed value: -"Result"
      • removedOutput schema / title
        Removed value: -"_WrappedResult"
    • Addedpermutations
    • Addedpirate_summary
    • Addedtext_web_search
    • Addedvonmises_random
  4. 5 tool updates
    • Removedgenerate_password
    • Removedpermutations
    • Removedpirate_summary
    • Removedtext_web_search
    • Removedvonmises_random
  5. 6 tool updates
    • First observedgenerate_password
    • First observedgreet
    • First observedpermutations
    • First observedpirate_summary
    • First observedtext_web_search
    • First observedvonmises_random

TDQS

B3.3/5.0

Scored across 5 tools

Disambiguation5/5

Each tool performs a clearly distinct function: greeting, password generation, web search, combinatorics calculation, and Python execution. There is no overlap or ambiguity between them.

Naming Consistency2/5

Tool names follow inconsistent conventions: grep uses a bare verb, generate_password and run_python_code use verb_noun, text_web_search is a noun phrase, and permutations is a bare noun. The mixed patterns make the set feel uncoordinated.

Tool Count5/5

Five tools is a reasonable number for a small utility-oriented MCP server. Each tool occupies a distinct niche and none feel redundant or excessive.

Completeness2/5

The server has no coherent domain to assess for completeness; the tools appear to be an arbitrary grab-bag rather than a cohesive workflow. There are obvious utilities one might expect from a Python-oriented server that are absent, such as file operations or package management, but the scope is too unclear to define true gaps.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • F
    license
    B
    quality
    D
    maintenance
    A simple example MCP server that demonstrates basic server functionality and can be easily run using uv package manager. Provides a minimal implementation for learning and development purposes.
    1
    -
  • A
    license
    Not graded
    quality
    F
    maintenance
    Enables dynamic creation and code generation of MCP servers using FastMCP, with tools for adding custom tools, resources, and generating runnable Python code.
    41
    MIT