Paws-on-MCP
A teaching MCP server in Python: Hacker News search, GitHub repository details and examples of model sampling requests
- 326 ★ on the repository
- Last commit
Extended access
Why this level
- The server goes online to Hacker News and GitHub
- The request_client_roots tool asks the client for file system roots
Install
- Works in
Manual install
git clone https://github.com/hemanth/paws-on-mcp.git && cd paws-on-mcp && pip install -r requirements.txt && cd src && python mcp_server.pyThe server comes up at http://127.0.0.1:8000/mcp/. Add this address to your MCP client.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The server goes online to Hacker News and GitHub
- The request_client_roots tool asks the client for file system roots
This is third-party code. Review the repository files before installing.
What it does
Paws-on-MCP shows in working code how the main parts of MCP specification version 2025-03-26 fit together: tools, resources, prompts, roots and sampling. The server is written in Python and runs over HTTP on a local address. The subject matter is deliberately simple. The search_hackernews tool searches Hacker News stories, and get_github_repo_info returns details about a GitHub repository. Three tools ask the client to run a model, for example code_review_with_ai for code review. Such a request carries a model hint and priorities for intelligence, cost and speed. There are fifteen resources, including top stories, trending GitHub repositories by language and server status. Fourteen prompt templates are grouped into five families, from technology trends to code review. For checking, the repository includes a command-line client and a test suite.
Who it is for. For developers learning MCP who want to see sampling with model preferences, resources and prompt templates in a ready server.
Good fit when
- You are learning MCP and want code where tools, resources, prompts and roots sit side by side
- You need a sampling request example with a model hint
- You are building your own server and want a folder structure with tests for each capability type as a base
- You want to compare your client with a server that returns resources under several address schemes
Not a fit when
- You need a working tool for daily GitHub work: GitHub's official server exists for that
- You need a server for real workloads with support: the project is educational
- You need a one-command install from a package registry: there is no package, the server runs from a clone
- Your client cannot handle sampling requests: the three tools with AI analysis will return nothing
Example request
Find five fresh Python stories on Hacker News and analyze the trends with sampling. Show the top daily trending Python repositories on GitHub.MCP
- Transport
- http
- Authentication
- not required
Limitations
The server runs only from a repository clone, and there is no registry package. You need Python and the dependencies from requirements.txt. According to the author, 3 of 5 test groups pass: roots and extended sampling hit concurrency limits in the test harness. Data comes from the open Hacker News and GitHub APIs, and setup needs no keys. Sampling tools only form a model request and return the status ready_for_client, while the answer itself comes from the model on the client side. The repository has not been updated since June 2025.
How to disable. Stop the server process with Ctrl+C and remove the http://127.0.0.1:8000/mcp/ address entry from your client configuration. The repository clone can be deleted like an ordinary folder.
FAQ
How do I run Paws-on-MCP?
Clone the repository, install dependencies with `pip install -r requirements.txt`, go to src and run `python mcp_server.py`. The server comes up at http://127.0.0.1:8000/mcp/.
Which tools does the server have?
The author counts nine. Besides Hacker News search and repository details, they cover server roots and prompts, three sampling tools and request_client_roots, which asks the client for its roots.
What is extended sampling in this project?
The create_sampling_request tool accepts a model hint such as claude-3-sonnet, priorities, temperature and a token limit. The server returns the method sampling/createMessage and the status ready_for_client.
How do I check the server without an MCP client?
Use the command-line client: `python mcp_cli_client.py tool search_hackernews --args '{"query": "AI", "limit": 3}'` or read a resource with `python mcp_cli_client.py resource hackernews://top/10`.
How is Paws-on-MCP different from the official GitHub server?
It is a teaching implementation of the protocol where GitHub gives only repository details and a trending list. The official server covers code, issues, pull requests and Actions for daily work.
Discussion
No questions or reviews yet.
Related
MCP serversA local code graph with version history: an MCP server that tells the agent who calls a function and what an edit breaks
An MCP server that builds a code graph once and serves the answer to the agent instead of re-reading files
Ref's MCP server: documentation search for APIs and libraries that hands the agent only the relevant parts of pages
Docs MCP Server
Grounded Docs MCP Server
A local MCP server that indexes docs from websites, GitHub, npm, PyPI and files and gives the agent version-aware search
An MCP server and CLI for code research: search and understand your project and all of GitHub with fewer tokens
An MCP server that lets an agent read files, search code and run commands in a workspace
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Paws-on-MCP (this entry) | no | not required | 326 | |
| GitHub MCP Server | no | key is optional | 34,064 | GitHub's official server for code, issues, pull requests and Actions |
| Idea Reality MCP | no | not required | 826 | checks whether your idea already exists across GitHub, npm, PyPI and Hacker News |
README in short
The project is built on FastMCP, and a diagram shows how the server parts connect. A current status section lists what works and what is limited.