atlas-przetargow-mcp-py

Polski

Atlas Przetargow Polish public procurement API MCP server. A Python/FastMCP rewrite of the official TypeScript server with several upstream bugs fixed and new tender-analysis tools added.

Table of contents

• Tools
• Fixed vs upstream TS server
• Environment variables
• Wiring it up
• Local run

Tools

Tool	Parameters	Description
search_tenders	search?, buyer_nip?, cpv?, city?, province?, notice_type?, order_kind?, date_from?, date_to?, value_min?, value_max?, sort?, page=1, limit=20	Search BZP + TED tenders with filters
get_tender	tender_id: str, full: bool = False	Tender details; full=True includes complete notice text
get_tender_timeline	tender_id: str	Full notice chain of a procedure (announcement, revisions, result, performance)
get_tender_offers	tender_id: str	Offers count and lowest/highest/winning prices from result notices
extract_contract_value	tender_id: str	Contract/order money amounts extracted from notice text
get_buyer	nip: str, include_winning_contractors: bool = True	Buyer profile + contractors that most often win its tenders
get_contractor	nip: str, include_winning_buyers: bool = True	Contractor profile with win geography + top buyers
search_entities	query: str, entity_type?, limit=10	Find buyers/contractors by name (returns NIP)
search_cpv	query: str, limit=10	Look up CPV codes by Polish keyword
get_category_stats	cpv: str, window="year"	Category stats: count, median value, avg offers, avg deadline
get_province_stats	province?, city?	Province ranking, single province, or city drill-down
raw_request	path: str, params_json?	Escape hatch: GET any /api/* endpoint

Fixed vs upstream TS server

Bugs found while testing @atlasprzetargow/mcp v0.1.1:

1. buyerNip filter sent as buyerNip while the API expects buyer_nip — filter silently ignored. Fixed here.
2. get_buyer winning contractors read from winners.contractors while the API returns {"data": [...]} — section never rendered. Fixed here.
3. City stats returned an empty header although /api/stats/city/{city}/top-buyers returns data. Fixed here.
4. get_category_stats requested window can be ignored by the API (asks for year, returns 90 days) — this server returns the actual days value so the discrepancy is visible.
5. get_contractor returned 3 lines; this server returns the full profile (win geography, shares) plus winning buyers.

New tools not present upstream: get_tender_timeline, get_tender_offers, extract_contract_value, raw_request.

Environment variables

Variable	Required	Description
ATLAS_PRZETARGOW_MCP_PY_API_BASE	no	API base (default https://atlasprzetargow.pl)
ATLAS_PRZETARGOW_MCP_PY_API_KEY	no	Key for /api/llm/* AI summary endpoints
ATLAS_PRZETARGOW_MCP_PY_TIMEOUT	no	Request timeout in seconds (default 20)

Wiring it up

Only requirement: uv (https://docs.astral.sh/uv/). Nothing else to install.

Claude Code

claude mcp add atlas-przetargow-mcp-py -- uvx --from git+https://github.com/dam2452/atlas-przetargow-mcp-py.git atlas-przetargow-mcp-py

Claude Desktop / other MCP client

{
  "mcpServers": {
    "atlas-przetargow-mcp-py": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dam2452/atlas-przetargow-mcp-py.git", "atlas-przetargow-mcp-py"]
    }
  }
}

After pushing a new version: uv cache clean and restart the client.

Local run

uv run --directory . atlas-przetargow-mcp-py

Tests (manual):

uv run --directory . --with pytest pytest test/