# procurement-awards-mcp

国の調達の落札実績を、年度・案件名・府省・法人番号で絞り込めます。複数年度の案件数や落札価格を府省別に比較することもできます。APIキーは不要です。[uv](https://docs.astral.sh/uv/) と Git が必要です。Python 3.12以上に対応しています。

[MCP登録](#mcpクライアントに登録する) · [CLI](#cliで使う) · [Pythonライブラリ](#pythonライブラリとして使う)

## MCPクライアントに登録する

[uv](https://docs.astral.sh/uv/) と Git を用意し、リポジトリをクローンします。Python 3.12以上が必要です。

```sh
git clone https://github.com/koizumikento/procurement-awards-mcp.git
cd procurement-awards-mcp
uv sync --locked
```

以下の `/absolute/path/to/procurement-awards-mcp` は、クローン先の絶対パスに置き換えてください。Windowsでも `C:/projects/procurement-awards-mcp` のようにスラッシュで指定できます。

### Codex

```sh
codex mcp add procurement-awards-mcp -- uv --directory "/absolute/path/to/procurement-awards-mcp" run --locked procurement-awards-mcp
codex mcp list
```

`codex mcp list` で登録を確認し、Codexの新しいセッションで `/mcp` を開くと、接続状態を確認できます。[Codexの公式設定ガイド](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)

Codexのデスクトップアプリでは、設定の「MCP servers」でSTDIOサーバーを追加し、下のJSON例と同じコマンド・引数を指定する方法もあります。

### Claude Desktop / Cursor

次のファイルに設定します。

- Claude Desktop（Windows） `%APPDATA%/Claude/claude_desktop_config.json`
- Claude Desktop（macOS） `~/Library/Application Support/Claude/claude_desktop_config.json`
- Cursor `.cursor/mcp.json`（プロジェクト内）

既に `mcpServers` がある場合は、その中にサーバーの項目を追加してください。保存後にクライアントを再起動し、ツールが表示されるか確認します。[設定ファイルの場所と接続手順](https://py.sdk.modelcontextprotocol.io/get-started/real-host/)

```json
{
  "mcpServers": {
    "procurement-awards-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/procurement-awards-mcp",
        "run",
        "--locked",
        "procurement-awards-mcp"
      ]
    }
  }
}
```

`uv` が見つからない場合は、設定のコマンドに実行ファイルの絶対パスを指定してください。

登録後は、チャットで次のように聞けます。

> 2025年度の『地図』に関する落札実績を3件探して、落札先と落札価格を教えて。

> 2023年度と2024年度の『図書』に関する落札実績を府省別に集計して、案件数を比較して。

## ツール

### `search_awards`

`search_awards` で年度別全件または日次差分を、案件名・府省・法人番号で絞り込みできます。

```json
{
  "fiscal_year": 2025,
  "query": "地図",
  "limit": 3
}
```

年度別の全件データを検索するには `fiscal_year` を指定します。使うのは調達ポータルが月ごとに公表するファイルです。特定の日に追加された落札実績を探すには、日次差分ファイルの作成日を `published_on` に指定します。落札決定日での検索には使えません。日次差分の提供期間は過去約2か月です。

複数の事業者が落札した案件では、事業者ごとに結果を返します。落札価格は精度を保つため、元データの文字列で返します。

検索は取得したZIPに対して手元で実行します。ZIPはディスクに保存せず、同じ実行プロセス内で最大2件を保持します。同じ30分枠の照会では取得済みのZIPを再利用します。

### `summarize_awards`

年度別ファイルを1〜3年度指定して、年度・府省コードごとに案件数と価格を集計します。案件名の部分一致（`query`）や府省コード（例 `"L1"` は法務省）で絞り込めます。各年度に使用したファイル名とダウンロードURLを返します。

| 結果 | 数え方 |
| --- | --- |
| `matching_row_count` | 条件に一致する落札実績の行数 |
| `distinct_case_count` | 一致する行が1つ以上ある調達案件番号の数 |
| `ambiguous_case_count` | 同じ年度・府省・案件番号で、元ファイルに複数行ある案件数 |
| `priced_case_count` / `unpriced_case_count` | 元ファイルに1行だけある案件を、有効な落札価格の有無で区分した件数 |
| `single_row_award_price_total` | 価格が有効な単一行の案件だけの合計。小数精度を保つ文字列で、該当がなければ `null` |

同じ案件に複数の落札行がある場合は、重複計上を避けるため価格集計から除外します。府省全体の落札価格を比較する場合は、価格集計から除外された案件数も確認してください。

## CLIで使う

上の登録手順でクローンしたディレクトリで実行します。

```sh
uv run procurement-awards-mcp search-awards --fiscal-year 2025 --query "地図" --limit 3
uv run procurement-awards-mcp summarize-awards --fiscal-year 2023 --fiscal-year 2024 --query "図書" --ministry-code L1
```

結果は標準出力にUTF-8のJSONで出力します。コマンドの引数は `uv run procurement-awards-mcp search-awards --help` で確認できます。

## Pythonライブラリとして使う

自分のPythonプロジェクト（`pyproject.toml` があるディレクトリ）で依存関係に追加します。

```sh
uv add "git+https://github.com/koizumikento/procurement-awards-mcp.git@main"
```

次のコードを `example.py` に保存し、同じディレクトリで `uv run python example.py` を実行します。

```python
import asyncio

from procurement_awards_mcp import search_awards, summarize_awards

result = asyncio.run(search_awards(fiscal_year=2025, query="地図", limit=3))
print(result)
print(asyncio.run(summarize_awards([2023, 2024], query="図書")))
```

イベントループがある環境では、関数を直接 `await` します。

## 出典と利用条件

コードはMIT Licenseです。上流データの権利と利用条件は各提供元の定めに従います。[公式仕様](https://www.p-portal.go.jp/pps-web-biz/resources/app/pdf/rakusatsuopendata.pdf) · [利用案内](https://www.p-portal.go.jp/pps-web-biz/resources/app/html/sitepolicy.html)

## 開発

```sh
uv sync --locked
uv run ruff check .
uv run ty check
uv run pytest
uv build
```