Exif MCP

1# exif-mcp
2 
3An MCP server that allows LLMs (or humans) to read image metadata on-demand, entirely offline. Based on the excellent exifr library it's exremely fast and does not rely on any external tools.
4 
5Usecases:
6* Analyze image metadata and visualize it
7* Perform analysis of your image library: what are my most used cameras?  Lens distribution?  Which dates of the week I take most pictures on?  Most favorite locations?
8* Debugging image manipulation code.
9 
10Ths tool is used extensively by the reverse geolocation service [PlaceSpotter](https://www.placespotter.com/) for development and testing.
11 
12## Overview
13 
14`exif-mcp` is a Model Context Protocol (MCP) server that provides tools for extracting various metadata segments from images. Built with TypeScript, it leverages the excellent [exifr](https://github.com/MikeKovarik/exifr) library to parse metadata from images in common formats like JPEG, PNG, TIFF, and HEIC.  This allows this service to parse image metadata without executing any external tools which allows it to be both highly efficient and secure.
15 
16### Features
17 
18- **Local operation**: Works completely offline with no remote network required
19- **Multiple segments**: Extracts EXIF, GPS, XMP, ICC, IPTC, JFIF, and IHDR metadata
20- **Various input formats**: Supports JPEG, TIFF, HEIC/AVIF, and PNG
21- **Flexible image sources**: Read from file system, URLs, base64 data, or buffers
22- **Specialized tools**: Get orientation, rotation info, GPS coordinates, and thumbnails
23 
24## Installation
25 
26```csh
27# Clone the repository
28git clone https://github.com/stass/exif-mcp.git
29cd exif-mcp
30 
31# Install dependencies
32npm install
33 
34# Build the project
35npm run build
36```
37 
38## Usage
39### Claude Desktop
40 
41Put this into Claude config file (claude_desktop_config.json):
42```json
43"mcpServers": {
44    "exif-mcp": {
45      "command": "node",
46      "args": [
47        "/path/to/exif-mcp/dist/server.js"
48      ]
49    }
50  },
51```
52 
53Restart Claude.  Now you can ask Claude to inspect images for you or e.g. find files taken with specific camera.  This works best in combination with filesystem MCP tools so Claude can find files and list directories.
54 
55### Starting the server
56 
57```csh
58# Start the server
59npm start
60 
61# For development with auto-reload
62npm run dev
63```
64 
65The server uses the `StdioServerTransport` from the MCP SDK, making it compatible with any MCP client that supports STDIO transport.
66 
67You can use mcp-proxy to enable remote access.
68 
69### Available Tools
70 
71The following tools are provided by the server:
72 
73| Tool name | Description |
74|-----------|-------------|
75| `read-metadata` | Reads all or specified metadata segments |
76| `read-exif` | Reads EXIF data specifically |
77| `read-xmp` | Reads XMP data |
78| `read-icc` | Reads ICC color profile data |
79| `read-iptc` | Reads IPTC metadata |
80| `read-jfif` | Reads JFIF segment data |
81| `read-ihdr` | Reads IHDR segment data |
82| `orientation` | Gets image orientation (1-8) |
83| `rotation-info` | Gets rotation and flip information |
84| `gps-coordinates` | Extracts GPS coordinates |
85| `thumbnail` | Extracts embedded thumbnail |
86 
87### Debugging with MCP Inspector
88 
891. Start the inspector: `npx @modelcontextprotocol/inspector node dist/server.js`
902. Connect to it with MCP Inspector using the STDIO transport
913. Call a tool, e.g., `read-metadata` with parameter:
92   ```json
93   {
94     "image": {
95       "kind": "path",
96       "path": "/path/to/image.jpg"
97     }
98   }
99   ```
1004. You cal also use MCP inspector command line like this: `npx @modelcontextprotocol/inspector --cli node dist/server.js --method tools/call --tool-name read-exif --tool-arg image='{"kind": "path", "path": "/path/to/image.jpeg"}' --tool-arg pick="[]"`
101 
102### Image Source Types
103 
104The server supports multiple ways to provide image data:
105 
106```typescript
107// From local file system
108{
109  "kind": "path",
110  "path": "/path/to/image.jpg"
111}
112 
113// From URL (http, https, or file://)
114{
115  "kind": "url",
116  "url": "https://example.com/image.jpg"
117}
118 
119// From base64 data (raw or data URI)
120{
121  "kind": "base64",
122  "data": "data:image/jpeg;base64,/9j/4AAQSkZ..."
123}
124 
125// From base64 buffer
126{
127  "kind": "buffer",
128  "buffer": "/9j/4AAQSkZ..."
129}
130```
131 
132## Development
133 
134### Running Tests
135 
136```bash
137# Run tests
138npm test
139 
140# Run tests with watch mode
141npm run test:watch
142```
143 
144### Project Structure
145 
146```
147exif-mcp/
148├── src/
149│   ├── server.ts         # Main entry point
150│   ├── tools/
151│   │   ├── index.ts      # Tool registration
152│   │   ├── loaders.ts    # Image loading utilities
153│   │   └── segments.ts   # exifr options builders
154│   └── types/
155│       └── image.ts      # Type definitions
156├── tests/                # Test files
157└── README.md
158```
159 
160## Error Handling
161 
162The server provides standardized error handling for common issues:
163 
164- Unsupported formats or missing metadata
165- Network fetch failures
166- Oversized payloads
167- Internal exifr errors
168 
169## License
170 
171BSD 2-clause
172 
173## Acknowledgements
174 
175- [exifr](https://github.com/MikeKovarik/exifr) - Extremely fast and robust EXIF parsing library
176