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. Since PyMCP tracks the cutting edge of FastMCP, these tools were dropped rather than pinned to a deprecated protocol era.

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 taget 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

7 tools
generate_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

A4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, indicating no side effects. The description adds that the password is random and optionally includes special characters, but does not elaborate on randomness source or security properties. This is adequate given the annotation coverage.

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 unnecessary words. Every word contributes to understanding the tool's purpose and parameters.

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 two-parameter tool with annotations, the description covers the essential functionality. It does not explain the character set or security guarantees, but these are not critical for basic usage.

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?

Input schema coverage is 100%, with each parameter fully described (length: min/max/default; use_special_chars: boolean/default). The description adds no additional meaning beyond paraphrasing the boolean parameter.

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 verb 'generate' and the resource 'random password', and it specifies the controllable parameters (length and special characters). There are no similar sibling tools, so no differentiation needed.

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 usage for generating passwords, but does not explicitly mention when to use it versus alternatives. However, given that no similar tools exist on the server, the lack of explicit guidance is acceptable.

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

greetA
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

A3.9/5.0
Behavior3/5

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

Annotations already indicate readOnlyHint=true; description aligns as a read operation but adds no further behavioral details beyond that.

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?

Single sentence, no extraneous information, efficiently conveys the purpose.

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?

Given the tool's simplicity, annotations, and presence of output schema, the description is sufficient for an agent to understand and invoke the tool.

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 has 100% parameter description coverage; the tool description does not add additional meaning beyond what the schema provides.

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?

Describes specific action (greet) and resource (caller) with a clear result (Hello World message). Clearly distinguishable from unrelated siblings like generate_password or run_python_code.

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?

No explicit when-to-use or when-not-to-use guidance, but usage is implicitly clear due to the simple purpose and unrelated siblings.

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

permutationsA
Read-only
Inspect

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

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

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

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

Annotations declare readOnlyHint=true; description adds that it calculates without repetition and with order. No mention of edge cases (e.g., k>n, k=null) or error handling. Basic behavioral traits disclosed but not exhaustive.

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?

Single sentence, 16 words, to the point. No redundant information.

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?

Output schema exists; basic definition covers main purpose. Lacks details on return format or behavior for null k or k>n, but given tool simplicity, it's mostly complete.

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 has 100% description coverage; description restates param purpose without adding formula or additional semantics. Baseline 3 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 precisely defines permutations: order matters, no repetition. Verb 'Calculate' and resource 'number of permutations' are clear. Distinguishes from combinations and other combinatorial operations.

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?

Implied usage (when order matters, no repetition) but no explicit when-not-to-use or alternatives. Sibling tools are unrelated, so no confusion, but lack of guidance reduces score.

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

pirate_summaryAInspect

Summarise the given text in a pirate style. This is an example of a tool that can use LLM sampling to generate a summary.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations, the description carries full burden. It mentions 'LLM sampling', implying a generative process with potential latency/cost, but does not disclose whether the tool is read-only, idempotent, or has any side effects. Some transparency but incomplete.

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 concise sentences that front-load the purpose and add contextual note about LLM sampling. No wasted words.

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 single-parameter tool with an output schema, the description covers the essential behavior. It could mention output format briefly, but the existence of output schema mitigates this.

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 has 0% coverage for the 'text' parameter. The description adds meaning by identifying 'the given text' as the input, but does not elaborate on format, constraints, or expected length. Moderate compensation for low 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 verb 'Summarise' and the resource 'the given text in a pirate style', and it distinguishes from siblings which are unrelated tools like password generation or code execution.

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?

No guidance is provided on when to use this tool versus alternatives, such as other summarization tools or the sibling tools. The description does not mention prerequisites or exclusion criteria.

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

run_python_codeCInspect

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

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYes
inputsNo
script_nameNomain.py
check_typesNo
type_definitionsNo

TDQS

C2.4/5.0
Behavior2/5

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

With no annotations, the description must fully convey behavioral traits. It only states that output or error messages are returned, but omits critical details like execution environment, sandboxing, side effects, or resource limits. This is insufficient for safe and effective use.

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 just 10 words in a single sentence, which is concise. However, it lacks structure (e.g., bullet points, sections) and sacrifices important details for brevity. It is not well-organized for an agent to quickly parse key information.

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?

This tool involves code execution, which has high complexity and risk. Without output schema, annotations, or parameter descriptions, the description leaves the agent with almost no context about how to use it correctly or what to expect. It is severely incomplete.

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%, meaning the description must compensate by explaining parameters. It does not mention any of the 5 parameters (code, inputs, script_name, check_types, type_definitions), providing no semantics beyond their names. This is a critical gap.

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

Purpose4/5

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

The description clearly states the action ('Run the given Python code') and the result ('return the output or error message'). It is specific and unambiguous, but could be improved by specifying it executes arbitrary code and captures stdout/stderr. Given the sibling tools are all distinct (e.g., generate_password, greet), confusion is unlikely.

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?

No guidance is provided on when to use this tool versus alternatives or any prerequisites. The description does not mention security considerations, such as that code execution can be dangerous, nor does it clarify expected use cases. This is a minimal viable score.

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

vonmises_randomBInspect

Generate a random number from the von Mises distribution. This is an example of a tool that uses elicitation to obtain the required parameter kappa (κ).

ParametersJSON Schema
NameRequiredDescriptionDefault
muYesThe mean angle mu (μ), expressed in radians between 0 and 2π

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior3/5

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

With no annotations, the description partially discloses behavior by mentioning elicitation for kappa, but it's vague. It does not explain how elicitation works or what happens when called, leaving uncertainty about the required kappa parameter.

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

Conciseness4/5

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

The description is concise at two sentences, with the main purpose upfront. The second sentence adds useful but non-essential context, though it could be integrated more smoothly.

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?

Despite having an output schema, the description fails to clarify how the elicitation process works for the required kappa parameter. This omission makes the tool incomplete for an agent to invoke correctly, as the agent might assume only mu is needed.

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 coverage is 100% for mu, with a clear description in the schema. The tool description adds no additional meaning beyond stating the elicitation for kappa, which is not a parameter. Baseline 3 is appropriate.

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

Purpose4/5

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

The description clearly states it generates a random number from the von Mises distribution, with a specific verb and resource. However, the mention of elicitation for kappa (κ), which is not in the input schema, could confuse the purpose. The tool differentiates from siblings like generate_password or greet.

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?

There is no guidance on when to use this tool versus alternatives or when not to use it. The description does not provide context or exclusions.

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

TDQS

B3.2/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: password generation, greeting, combinatorial calculations, pirate-style summarization, web search, and statistical random number generation. The descriptions reinforce unique functionalities, making misselection unlikely.

Naming Consistency2/5

Naming is inconsistent with mixed conventions: snake_case (generate_password, pirate_summary, text_web_search, vonmises_random) and single words (greet, permutations). There is no predictable verb_noun pattern, and the styles vary chaotically across the set.

Tool Count3/5

With 6 tools, the count is borderline for a general-purpose utility server like PyMCP. It feels slightly thin given the broad scope implied by the diverse tools, but it's not severely mismatched; it could benefit from a few more cohesive additions.

Completeness2/5

The tool set is severely incomplete for a utility domain, lacking obvious gaps like file operations, data formatting, or common mathematical functions beyond permutations and von Mises. The tools are disparate without covering core utility workflows, leading to potential agent dead ends.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

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

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/anirbanbasu/pymcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server